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Preface 


Intended Audience 


This manual is intended for programmers who want to invoke and use the 
functions provided by OpenVMS utilities. 


Document Structure 


Chapter 1 introduces the utility routines and lists the documentation format used 
to describe each set of utility routines, as well as the individual routines in each 
set. Each subsequent chapter contains an introduction to a set of utility routines, 
a programming example to illustrate the use of the routines in the set, and a 
detailed description of each routine. 


This manual presents the following utility routine sets: 


Access Control List (ACL) editor routine 
Backup API routine 

Command Language | nterface (CLI) routines 
Common File Qualifier routines 

Convert (CONVERT) routines 

Data Compression/E xpansion (DCX) routines 
DEC Text Processing Utility (DECTPU) routines 


DIGITAL Distributed Time Service (DECdts) Portable Applications 
Programming Interface 


EDT routines 

Encryption (ENCRYPT) routines 

File Definition Language (F DL) routines 
Librarian (LBR) routines 

Lightweight Directory Access Protocol (LDAP) routines 
LOGINOUT (LGI) routines 

Mail utility (MAIL) routines 

National character set (NCS) utility routines 
Print Symbiont Modification (PSM) routines 
Symbiont/] ob Controller Interface (SMB) routines 
Sort/M erge (SOR) routines 

Traceback facility (TBK) routines 


Xvil 


Related Documents 


For information about HP OpenVMS products and services, visit the following 
World Wide Web address: 


http: //www.hp.com/go/openvms 


Reader’s Comments 


HP welcomes your comments on this manual. Please send comments to either of 
the following addresses: 
Internet openvmsdocG@hp.com 


Postal Mail Hewlett-Packard Company 
OSSG Documentation Group, ZK O3-4/U 08 
110 Spit Brook Rd. 
Nashua, NH 03062-2698 


How To Order Additional Documentation 


For information about how to order additional documentation, visit the following 
World Wide Web address: 


http: //www.hp.com/go/openvms/doc/order 


Conventions 
The following conventions may be used in this manual: 
164 Abbreviation representing "HP OpenVMS for Integrity 
servers". 
Ctrl/x A sequence such as Ctrl/x indicates that you must hold down 


the key labeled Ctrl while you press another key or a pointing 
device button. 


PF1x A sequence such as PF 1 x indicates that you must first press 
and release the key labeled PF 1 and then press and release 
another key or a pointing device button. 


Return In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


In the HTML version of this document, this convention appears 
as brackets, rather than a box. 


Horizontal ellipsis points in examples indicate one of the 
following possibilities: 


e Additional optional arguments in a statement have been 
omitted. 


e The preceding item or items can be repeated one or more 
times. 


e Additional parameters, values, or other information can be 
entered. 


Vertical ellipsis points indicate the omission of items from 
a code example or command format; the items are omitted 
because they are not important to the topic being discussed. 
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[] 


i} 


bold type 


italic text 


Example 


UPPERCASE TYPE 


numbers 


In command format descriptions, parentheses indicate that you 
must enclose choices in parentheses if you specify more than 
one. 


In command format descriptions, brackets indicate optional 
choices. You can choose one or more items or no items. 

Do not type the brackets on the command line. However, 
you must include the brackets in the syntax for OpenVMS 
directory specifications and for a substring specification in an 
assignment statement. 


In command format descriptions, vertical bars separate choices 
within brackets or braces. Within brackets, the choices are 
optional; within braces, at least one choice is required. Do not 
type the vertical bars on the command line. 


In command format descriptions, braces indicate required 
choices; you must choose at least one of the items listed. Do 
not type the braces on the command line. 


Bold type represents the introduction of a new term. It also 
represents the name of an argument, an attribute, or a reason. 


Italic text indicates important information, complete titles 
of manuals, or variables. Variables include information that 
varies in system output (Internal error number), in command 
lines ((PRODUCER=name), and in command parameters in 
text (where dd represents the predefined code for the device 
type). 


This typeface indicates code examples, command examples, and 
interactive screen displays. In text, this type also identifies 
URLs, UNIX commands and pathnames, PC-based commands 
and folders, and certain elements of the C programming 
language. 

Uppercase type indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 


A hyphen at the end of a command format description, 
command line, or code line indicates that the command or 
statement continues on the following line 


All numbers in text are assumed to be decimal unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 
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Introduction to Utility Routines 


A set of utility routines performs a particular task or set of tasks. For example, 
you can use the Print Symbiont Modification (PSM) routines to modify the print 
symbiont and the EDT routines to invoke the EDT editor from a program. 


Some of the tasks performed by utility routines can also be performed at the 
Digital Command Language (DCL) level (for example, the DCL command EDIT 
invokes the EVE editor). While DCL commands invoke utilities that let you 
perform tasks at your terminal, you can perform some of these tasks at the 


programming level through the use of the utility routines. 


When using a set of utility routines that performs the same tasks as the related 
utility, you should read the documentation for that utility; doing so will provide 
additional information about the tasks the routines can perform as a set. The 

following table lists the utilities and their corresponding routines: 


Utility or Editor 


Utility Routines 


Access control list editor 

Backup application programming interface 
Command Definition Utility 

Common File Qualifier routines 

Convert and Convert/Reclaim utilities 

Data Compression/E xpansion (DCX) facility 
DEC Text Processing Utility 


Digital Distributed Time Service (DECdts) portable 
applications programming interface 


EDT editor 

Encryption routines 

File Definition Language facility 
Librarian utility 


Lightweight Directory Access Protocol (LDAP) application 
programming interface 


LOGINOUT callout routines 

Mail utility 

National Character Set utility 

Print Symbiont Modification (PSM) facility 
Symbiont/] ob Controller Interface facility 
Sort/M erge utility 

Traceback facility 


ACL editor routine 
Backup API routine 
CLI routines 
UTIL$CQUAL routines 
CONVERT routines 
DCX routines 

DECTPU routines 
DECdts API routines 


EDT routines 
ENCRYPT routines 
FDL routines 
LBR routines 
LDAP API routines 


LGI routines 
MAIL routines 
NCS routines 
PSM routines 
SMB routines 
SOR routines 
TBK routines 
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When a set of utility routines performs functions that you cannot perform 

by invoking a utility, the functions provided by that set of routines is termed 

a facility. The following facilities have no other user interface except the 
programming interface provided by the utility routines described in this manual: 


Facility Utility Routines 
Data Compression/E xpansion facility DCX routines 
Print Symbiont Modification facility PSM routines 
Symbiont/) ob Controller Interface facility SMB routines 
Traceback faciltiy TBK routines 


Like all other system routines in the OpenVMS environment, the utility routines 
described in this manual conform to the HP OpenVMS Calling Standard. Note 
that for stylistic purposes, the calling syntax illustrated for routines documented 
in this manual is consistent. However, you should consult your programming 
language documentation to determine the appropriate syntax for calling these 
routines. 


Each chapter of this book documents one set of utility routines. Each chapter has 
the following major components, documented as a major heading: 


e An introduction to the set of utility routines. This component discusses the 
utility routines as a group and explains how to use them. 


e Oneor more programming examples that illustrate how the utility routines 
are used. 


e A series of descriptions of each utility routine in the set. 
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Access Control List (ACL) Editor Routine 


This chapter describes the access control list editor (ACL editor) routine, 
ACLEDIT$E DIT. User-written applications can use this callable interface of the 
ACL editor to manipulate access control lists (ACLs). 


2.1 Introduction to the ACL Editor Routine 


The ACL editor is a utility that lets you create and maintain access control lists. 
Using ACLs, you can limit access to the following protected objects available to 
system users: 


e Devices 

e Files 

¢ Group global sections 

e Logical name tables 

e« System global sections 
¢ Capabilities (VAX only) 
« Common event flag clusters 
* Queues 

e Resource domains 

e Security classes 

e Volumes 


The ACL editor provides one callable interface that allows the application 
program to define an object for editing. 


Note that the application program should declare referenced constants and return 
status symbols as external symbols; these symbols will be resolved upon linking 
with the utility shareable image. 


See the HP OpenVMS Programming Concepts Manual for fundamental 
conceptual information on the creation, translation, and maintenance of access 
control entries (ACEs). 


2.2 Using the ACL Editor Routine: An Example 
Example 2-1 shows a VAX BLISS program that calls the ACL editor routine. 
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Access Control List (ACL) Editor Routine 
2.2 Using the ACL Editor Routine: An Example 


Example 2-1 Calling the ACL Editor with a VAX BLISS Program 


BEGIN 


BEGIN 


LOCAL 
STATUS, 


LIBRARY ‘SYSSLIBRARY:LIB’ ; 
ROUTINE STARTUP = 


ODULE MAIN (LANGUAGE (BLISS32), MAIN = STARTUP) = 


! Routine return status 
ITMLST : BLOCKVECTOR [6, ITMSS_ITEM, BYTE] ; 


EXTERNAL LITERAL 
ACLEDITSV_JOURNAL, 


ACLEDITSV_PROMPT MODE, 


DITSC_OBJNAM, 
DITSC_OBJTYP, 
DITSC_OPTIONS; 


ACL 
ACL 
ACL 


He fi 


EXTERNAL ROUTINE 


ACLEDITSEDIT : 


CLISGET VALUE, 
CLISPRESENT, 
LIBSPUT_OUTPUT, 
STRSCOPY_DX; 


! Set up the ite 
CHSFILL (0, 6*ITMSS ITEM, 
ITMLST[0, ITMSW_ITMCOD 
ITMLST[0, ITM$W BUFSIZ 
ITMLST[0, ITM$L_BUFADR 
ITMLST[1, ITMSW_ITMCOD 
ITMLST[1, ITMSW_BUFSIZ 
ITMLST[1, ITM$L_BUFADR 
ITMLST[2, ITM$W_ITMCOD 
ITMLST[2, ITMSW BUFSIZ 
ITMLST[2, ITMSL_BUFADR 

1 * ACLEDITSV_JOURNAL) ; 
RETURN ACLEDITSEDIT (ITMLST) ; 
END; ! 
END 
ELUDOM 


2.3 ACL Editor Routine 
This section describes the ACL editor routine. 


! ACL editor item list 


ADDRESSING MODE (GENERAL), ! Main routine 


! Get qualifier value 
! See if qualifier present 
! General output routine 
! Copy string by descriptor 


list to 


pass back to TPU so it can figure out what to do. 


ITMLST) ; 

ACLEDITSC_OBJNAM; 

%CHARCOUNT (‘YOUR_OBJECT NAME’) ; 
SDESCRIPTOR ('’ YOUR OBJECT NAME’) ; 
ACLEDITSC_OBJTYP; 

4; 
UPLIT (ACLSC FILE); 


ACLEDITS$C_OPTIONS; 
4; 
UPLIT (1 * ACLEDITSV_PROMPT MODE OR 


End of routine STARTUP 
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Access Control List (ACL) Editor Routine 
ACLEDIT$EDIT 


ACLEDIT$EDIT—Edit Access Control List 


Format 


Returns 


Argument 


The ACLEDIT$EDIT routine creates and modifies an access control list (ACL) 
associated with any protected object. 


ACLEDIT$EDIT  item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


item_list 

OpenVMS usage: item _list_3 

type: longword (unsigned) 
access: read only 
mechanism: by descriptor 


Item list used by the callable ACL editor. The item_list argument is the address 
of one or more descriptors of arrays, routines, or longword bit masks that control 
various aspects of the editing session. 


Each entry in an item list is in the standard format shown in the following figure: 


Item code Buffer length 


Buffer address 


Return length address 


ZK-5012-GE 
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Access Control List (ACL) Editor Routine 
ACLEDIT$EDIT 


The following table provides a detailed description of each item list entry: 


Item Identifier Description 
ACLEDIT$C_OBJ NAM Specifies the name of the object whose ACL is being edited. 
ACLEDIT$C_OBJ TYP A longword value that specifies the object type code for the type 


or class of the object whose ACL is being edited. These type 
codes are defined in $ACLDEF. The default object type is FILE 


(ACL$C_FILE). 


ACLEDIT$C_OPTIONS Represents a longword bit mask of the various options available 
to control the editing session. 


Flag 


Function 


ACLEDIT$V_J OURNAL 


ACLEDIT$V_RECOVER 


ACLEDIT$V_KEEP_ 
RECOVER 


ACLEDIT$V_KEEP_ 
J OURNAL 


ACLEDIT$V_PROMPT_ 
MODE 


Indicates that the editing session is to 
be journaled. 


Indicates that the editing session is to 
be recovered from an existing journal 
file. 

Indicates that the journal file used to 
recover the editing session is not to be 
deleted when the recovery is complete. 


Indicates that the journal file used for 
the editing session is not to be deleted 
when the session ends. 


Indicates that the session is to use 
automatic text insertion (prompting) 
to build new access control list entries 
(ACEs). 
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Access Control List (ACL) Editor Routine 
ACLEDIT$EDIT 


Item Identifier 


Description 


ACLEDIT$C_BIT_TABLE 


ACLEDIT$C_CLSNAM 


Specifies a vector of 32 quadword string descriptors of strings that 
define the names of the bits present in the access mask. (The first 
descriptor defines the name of bit 0; the last descriptor defines 
the name of bit 31.) These descriptors are used in parsing or 
formatting an ACE. The buffer address field of the item descriptor 
contains the address of this vector. 


A string descriptor that points to the class name of the object 
whose ACL is being modified. The following are valid class 
names: 


* CAPABILITY (VAX only) 

* COMMON _EVENT_FLAG CLUSTER 
* DEVICE 

* FILE 

* GROUP_GLOBAL_SECTION 
* LOGICAL_NAME_TABLE 

* QUEUE 

* RESOURCE_DOMAIN 

* SECURITY_CLASS 

* SYSTEM _GLOBAL_SECTION 
* VOLUME 


If both OBJ TYP and CLSNAM are omitted, the object is assumed 
to belong to the FILE class. 


Description 


Use the ACLEDIT$EDIT routine to create and modify an ACL associated with 
any security object. 


Under normal circumstances, the application calls the ACL editor to modify an 
object’s ACL, and control is returned to the application when you finish or abort 
the editing session. 


If you also want to use a customized version of the ACL editor section file, the 
logical name ACLEDT$SECTION should be defined. See the HP OpenVMS 
Systen Management Utilities Reference Manual for more information. 


Condition Values Returned 


SS$ NORMAL 
RMS$_xxx 


Normal successful completion. 


See the OpenVMS Record Management Services 
Reference Manual for a description of OpenVMS 
RMS status codes. 
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Access Control List (ACL) Editor Routine 
ACLEDITS$EDIT 


TPU$ Xxx See Chapter 8 for a description of the TPU- 
specific condition values that may be returned by 
ACLEDIT$EDIT. 
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Backup (BACKUP) Routine 


This chapter describes the Backup application programming interface (API). 
User-written applications can use the Backup API to perform BACKUP 
operations. 


3.1 Introduction to the Backup API 


The Backup API allows application programs to save individual files or the 
contents of entire disk volume sets. The Backup API also allows application 
programs to get information about files or disk and tape volumes. 


In general, the Backup API gives application programs access to (relevant) 
BACKUP functions that are available to an interactive user via the DCL 
command BACKUP. The application program calls routine BACKUP$START 
with an argument that points to a variable-length array, which consists of 
option structures to specify the required BACKUP operation. The call to 
BACKUP$START in combination with the option structures in the variable- 
length array form the equivalent of a BACKUP command at DCL level. 


Each relevant BACKUP qualifier is represented by an option structure or 
combination of option structures. Each option structure consists of a longword 
that contains the option structure identifier, followed by a value field of 1 to 
7 longwords. Each option structure must be quadword-aligned within the 
variable-length array. There are six option structure types: 


Option Definition 
bck_opt_struct_adr 32-bit address 
bck_opt_struct_dsc Static string descriptor 
bck_opt_struct_dsc64 Reserved for use by HP 
bck_opt_struct_dt Date/Time quadword (ADT) 
bck_opt_struct_flag Logical bit flags 
bck_opt_struct_int 32-bit integer 


The option structure types are defined in the language definition files. Table 3-1 
lists the language definition files. 
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Table 3-1 Backup API Language Definition Files 


Media Format 


(Save Set) Backup Utility Data 
Language API Definitions Definitions Structures 
BASIC BAPIDEF.BAS BACK DEF.BAS BACKSTRUC.BAS 
BLISS BAPIDEF.R32 BACK DEF.R32 BACKSTRUC.R32 
C BAPIDEF.H BACK DEF.H BACKSTRUC.H 
Fortran BAPIDEF.FOR BACKDEF.FOR BACKSTRUC.FOR 
MACRO BAPIDEF.MAR BACKDEF.MAR BACKSTRUC.MAR 


See the HP OpenVMS System Management Utilities Reference Manual: A-L 
for detailed definitions of the DCL command BACKUP qualifiers. See the 
HP OpenVMS Systen Manager’s Manual, Volume 1: Essentials for detailed 
information about using BACKUP. You can also use the Help facility for more 
information about the Backup command and its qualifiers. 


3.2 Using the Backup API: An Example 


Example 3-1 shows a VAX C program that calls the Backup API. This program 
produces the same result as the following DCL command: 


$ BACKUP [.WRK]*.* A.BCK/SAVE 


Example 3-1 Calling the Backup API with a VAX C Program 


#include <stdio.h> 

#include <stdlib.h> 

#include <ssdef.h> 

#include <descrip.h> 

#include "sysSexamples:bapidef.h" 


typedef struct oad 


bck _opt_struct_dsc argl; 
bck_opt_struct_dsc arg2; 
bck_opt_struct_flag arg3; 
bck opt _struct_flag arg4; 
bck opt _struct_flag arg5; 


} buf_arg; 
struct dsc$descriptor 
input_dsc, 
output_dsc, 
event_type_ dsc; 
buf_arg myarg_ buff; 
unsigned int status; 


extern unsigned int backup$start (buf arg *myarg buff); 
unsigned int subtest (void *); 


static char input_str[] 
static char output_str[] 


2M [.wrk] we 
= "a.bck"; 


(continued on next page) 
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3.2 Using the Backup API: An Example 


Example 3-1 (Cont.) Calling the Backup API with a VAX C Program 


main () 


{ 


input_dsc.dsc$b dtype 
output _dsc.dsc$b dtype 


iT] 


input_dsc.dsc$b class 
output_dsc.dsc$b class 


I 


input_dsc.dsc$w length = sizeof (inp 
output_dsc.dsc$w_ length = sizeof (ou 


input_dsc.dsc$a_pointer 
output_dsc.dsc$a_pointer 


output_s 


yarg buff. 
yarg buff. 


argl. 
argl. 


op 
op 


.op 
.op 


.op 
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t_dsc = input_dsc; 


arg2 
arg2 


yarg buff. 
yarg buff. 


t_dsc_type 
t_dsc = output_dsc; 


3 


yarg buff.arg3 tion_type 


input_str; 


DSC$K_DTYPE T; 


DSC$K_CLASS S$; 


ut_str) ; 
tput_str) ; 


! 


os a 


t_dsc_type = BCK_OPT K INPUT; 


BCK_OPT_K OUTPUT; 


BCK OPT K SAVE SET OUT; 


3 


yarg buff.arg3.opt_ flag value = TRUE; 


.op 
.op 


.op 
.op 


backup$start (&myarg_buff) ; 


yarg buff. 
yarg buff. 


arg4 
arg4 


tion_type 
t_flag value 
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yarg buff. 
yarg buff. 


arg5 
arg5 


tion_type 
t_flag value 


FALSE; 


status 


exit (status) ; 


3.3 Backup API 
This section describes the Backup API. 


BCK_OPT K OPERATION TYPE; 
BCK_OP_K SAVE ; 


BCK_OPT_K END OPT; 
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Backup API 
BACKUP$START 


BACKUP$START—Call BACKUP Utility 


BACKUP$START is the entry point through which applications invoke the 
OpenVMS Backup utility. 


Format 
BACKUP$START  argument-buffer 
Returns 
OpenVMS usage: COND_VALUE 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Condition values that this routine can return are 
listed under Condition Values Returned. 
Argument 


argument-buffer 
OpenVMS usage: user-defined array 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Arguments that specify the BACKUP operation to be performed. The 
argument-buffer argument is the address of a variablelength array of one 

or more Backup API option structures that define the attributes of the requested 
BACKUP operation. The variable-length array is terminated by an option 
structure of 16 bytes that contains all zeros. Table 3-2 describes the option 
structures. 


Note 


The length of the terminating option structure is 2 longwords (16 bytes). 
The first longword identifies the option structure and has a value of 0. It 
is recommended that the second longword contain a value of 0. 


Table 3-2 BACKUP Option Siructure Types 
Option Structure Description 


BCK_OPT_K_END_OPT Flag that contains all zeros to denote the end of 
argument-buffer. This option structure consists 
of 2 longwords. The first longword, with a value 
of 0, identifies the BCK_OPT_K_END_OPT 
option structure. The second longword is ignored 
by BACKUP. However it is recommended that the 
second longword contain all zeros. 
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Backup API 
BACKUP$START 


Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_ALIAS 


BCK_OPT_K_ASSIST 


BCK_OPT_K_BACKUP 


BCK_OPT_K_BEFORE_TYPE 


Flag that specifies whether to maintain the 
previous behavior of multiple processing of alias 
and primary file entries. 
Values are TRUE (default) or FALSE. (See the 
BACKUP qualifier /ALIAS.) 
Note: Use of BCK_OPT_K_ALIAS and BCK_ 
OPT_K_PHYSICAL in the same call results in a 
fatal error. 
Flag that specifies whether to allow operator 
or user intervention if a request to mount a 
magnetic tape fails during a BACKUP operation. 
Values are TRUE (default) or FALSE. 
(See the BACKUP qualifier /ASSIST.) 
Flag that specifies whether to select files 
according to the BACKUP date written in the 
file header record. 
Values are TRUE or FALSE. Use this 
flag to set the corresponding logical bit 
flag for BCK_OPT_K_BEFORE_TYPE and 
BCK_OPT_K_SINCE_TYPE. 
(See the BACKUP qualifiers /BEFORE, /SINCE, 
and /BACKUP.) 
Logical bit flags that qualify the date specified 
in the BCK_OPT_K_BEFORE_VALUE option 
structure. Type can be one of the following: 
BCK_OPTYP_BEFORE_K_BACKUP 
Selects files last saved or copied by BACKUP 
before the date specified. Also selects files 
with no BACKUP date. 
BCK_OPTYP_BEFORE_K_CREATED 
Selects files created before the date specified. 
BCK_OPTYP_BEFORE_K_EXPIRED 
Selects files that have expired as of the date 
specified. 
BCK_OPTYP_BEFORE_K_MODIFIED 
(Default) Selects files last modified before the 
date specified. 
BCK_OPTYP_BEFORE_K_SPECIFIED 
Reserved for use by HP. 


(See the BACKUP qualifiers /BEFORE, 
/BACKUP, /CREATED, /EXPIRED, and 
/MODIFIED.) 
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Backup API 
BACKUP$START 


Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure Description 


BCK_OPT_K_BEFORE_VALUE Date-Time Quadword that specifies the date 
qualified by BCK_OPT_K_BEFORE_TYPE. You 
cannot use delta time. 

(See the BACKUP qualifier /BEFORE.) 


BCK_OPT_K_BLOCK Integer that specifies the block size in bytes for 
data records in the BACKUP save set. 
The default block size for magnetic tape is 8,192 
bytes. The default block size for disk is 32,256 
bytes. 
(See the BACKUP qualifier /BLOCK_SIZE.) 
BCK_OPT_K_CARTRIDGE_MEDIA_IN? 32-bit descriptor. 
Note: Use of BCK_OPT_K_CARTRIDGE_ 
MEDIA_IN and BCK_OPT_K_CARTRIDGE _ 
NAME_IN or any of the BCK_OPT_K_ 
SCRATCH _* option structures in the same call 
results in a fatal error. 
BCK_OPT_K_CARTRIDGE_NAME_IN? 32-bit descriptor. 
Note: Use of BCK_OPT_K_ CARTRIDGE _ 
NAME_IN and BCK_OPT_K_CARTRIDGE_ 
MEDIA_IN or any of the BCK_OPT_K_ 
SCRATCH _* option structures in the same call 
results in a fatal error. 
BCK_OPT_K_CARTRIDGE_SIDE_IN? 32-bit descriptor. 
Note: Use of BCK_OPT_ K_CARTRIDGE_SIDE_ 
IN without BCK_OPT_K_CARTRIDGE_NAME _ 
IN in the same call results in a fatal error. 
Note: Use of BCK_OPT_K_CARTRIDGE_SIDE 
IN with any of the BCK_OPT_K_ SCRATCH _* 
option structures in the same call results in a 
fatal error. 
BCK_OPT_K_CARTRIDGE_MEDIA_OUT?! 32-bit descriptor. 
Note: Use of BCK_OPT_K_CARTRIDGE_ 
MEDIA_OUT and BCK_OPT_K_ CARTRIDGE _ 
NAME_OUT or any of the BCK_OPT_K_ 
SCRATCH _* option structures in the same call 
results in a fatal error. 
BCK_OPT_K_CARTRIDGE_NAME_OUT?! 32-bit descriptor. 
Note: Use of BCK_OPT_K_CARTRIDGE_ 
NAME_OUT and BCK_OPT_K_CARTRIDGE_ 
MEDIA_OUT or any of the BCK_OPT K__ 
SCRATCH _* option structures in the same call 
results in a fatal error. 


1Reserved for use by Media Management Extension (MME) layered products. 
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Backup API 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_CARTRIDGE_SIDE_OUT! 


BCK_OPT_K_COMMAND 
BCK_OPT_K_COMMENT 


BCK_OPT_K_COMPARE 


BCK_OPT_K_CONFIRM 


BCK_OPT_K_CRC 


BCK_OPT_K_CREATED 


BCK_OPT_K_DCL_INTERFACE 
BCK_OPT_K_DELETE 


32-bit descriptor. 

Note: Use of BCK_OPT_K_CARTRIDGE_ 
SIDE_OUT without BCK_OPT_K_CARTRIDGE_ 
NAME_OUT in the same call results in a fatal 
error. 

Note: Use of BCK_OPT_K_CARTRIDGE_SIDE_ 
OUT with any of the BCK_OPT_K_SCRATCH_* 
option structures in the same call results in a 
fatal error. 

Reserved for use by HP. 

32-bit descriptor that specifies a comment string 
to be placed in the output save set. 

(See the BACKUP qualifier /COMMENT.) 

Flag that specifies whether to compare the entity 
specified by BCK_OPT_K_INPUT with the entity 
specified by BCK_OPT_K_ OUTPUT. Values are 
TRUE and FALSE (default). 

(See the BACKUP qualifier /COMPARE.) 

Flag that specifies whether to prompt for 
confirmation before processing each file 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /CONFIRM.) 

Flag that specifies whether the software cyclic 
redundancy check (CRC) is to be performed. 
Values are TRUE (default) and FALSE. 

(See the BACKUP qualifier /CRC.) 

Flag that specifies whether to select files 
according to the creation date written in the 
file header record. 

Values are TRUE or FALSE. 

Use this flag to set the corresponding logical 

bit flag for BCK_OPT_K_BEFORE_TYPE and 
BCK_OPT_K_SINCE_TYPE. 

(See the BACKUP qualifiers /BEFORE, /SINCE, 
and /CREATED.) 

Reserved for use by HP. 

Flag that specifies whether a copy or backup 
operation is to delete the input files from the 
input volume when the operation is complete. 
Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /DELETE.) 


1Reserved for use by Media Management Extension (MME) layered products. 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_DENSITY 


BCK_OPT_K_DISMOUNT 
BCK_OPT_K_DISPOSITION! 


BCK_OPT_K_DRIVE_CLASS IN! 
BCK_OPT_K_DRIVE_CLASS OUT! 
BCK_OPT_K_ENCRYPT2 
BCK_OPT_K_ENCRYPT_USERALG? 
BCK_OPT_K_ENCRYPT_USERKEY2 


BCK_OPT_K_ENCRYPT_KEY_VALUE2 


BCK_OPT_K_EVENT_CALLBACK 


BCK_OPT_K_EXACT_ORDER 


Integer that specifies the recording density of the 
output magnetic tape in bits per inch (bits/in). 
The density specified must be supported by the 
magnetic tape hardware. The default density is 
the current density on the output tape drive. (See 
the BACKUP qualifier /DENSITY.) 

Note: Use of BCK_OPT_K_DENSITY and BCK_ 
OPT_K_MEDIA_FORMAT in the same call 
results in a fatal error. 

Reserved for use by HP. 


Logical bit flags. Values are the following: 


BCK_OPTYP_DISP_K_KEEP 
BCK_OPTYP_DISP_K_RELEASE 


32-bit descriptor. 

32-bit descriptor. 

Flag. 

32-bit descriptor. 

32-bit descriptor. 

Note: Use of BCK_OPT_K_ENCRYPT_ 
USERKEY and BCK_OPT_K_ENCRYPT_KEY_ 
VALUE in the same call results in a fatal error. 
32-bit descriptor. 

Note: Use of BCK_OPT_K_ENCRYPT_KEY_ 
VALUE and BCK_OPT_K_ENCRYPT_USERKEY 
in the same call results in a fatal error. 


Address of a routine in the calling application 

to be called to process BACKUP events. See the 
Description section for detailed information about 
event callbacks. 


Flag that specifies whether a BACKUP operation 
is to accept an exact order of tape volume labels, 
preserve an existing volume label, and prevent 
previous volumes of a multivolume save operation 
from being overwritten. 

Values are TRUE (default) and FALSE. 

(See the BACKUP qualifier /EXACT_ ORDER.) 


1Reserved for use by Media Management Extension (MME) layered products. 
2Reserved for future use by a security utility or layered product. 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_EXCLUDE 


BCK_OPT_K_EXPIRED 


BCK_OPT_K_FAST 


BCK_OPT_K_FILE_CALLBACK 
BCK_OPT_K_FILEMERGE 
BCK_OPT_K_FULL 


BCK_OPT_K_GROUP 


BCK_OPT_K_HANDLE 


32-bit descriptor that specifies the name of 

an input file to be excluded from the current 
BACKUP save or copy operation. Wildcards 

are permitted. Each file specification, whether 
wildcarded or not, requires its own BCK_OPT_ 
K_EXCLUDE option structure (lists are not 
supported). 

(See the BACKUP qualifier /EXCLUDE.) 

Flag that specifies whether to select files 
according to the expiration date written in the file 
header record. 

Values are TRUE or FALSE. 

Use this flag to set the corresponding | ogical 

bit flag for BCK_OPT_K_BEFORE_TYPE and 
BCK_OPT_K_ SINCE TYPE. 

(See the BACKUP qualifiers (BEFORE, /SINCE, 
and /EXPIRED.) 

Flag that specifies whether to reduce processing 
time by performing a fast file scan of the input 
specifier. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /FAST.) 

Reserved for use by HP. 

Reserved for use by HP. 

Flag that specifies whether to display information 
produced by a BCK_OPT_K_LIST value of TRUE 
in a format similar to that produced by the DCL 
command DIRECTORY/FULL. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifiers /LIST and /FULL.) 
Integer that specifies the number of backup 
blocks or backup buffers BACKUP places in each 
redundancy group. 

The default is 10 blocks. 

(See the BACKUP qualifier /GROUP_SIZE.) 
Reserved for use by HP. 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_IGNORE_TYPES 


BCK_OPT_K_IMAGE 


BCK_OPT_K_INCREMENTAL 


BCK_OPT_K_INITIALIZE 


BCK_OPT_K_INPUT 
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Logical bit flags that override tape labeling 
checks or restrictions placed on files. Values are 
one of the following: 
BCK_OPTYP_IGNORE_K_ACCESS 
Processes files on a tape that is protected by 
a volume accessibility character, or a tape 
created by HSC Backup. Applies to all tapes 
in the save set. 
BCK_OPTYP_IGNORE_K_INTERLOCK 
Processes files otherwise inaccessible because 
of file access conflicts. 
BCK_OPTYP_IGNORE_K_LABELS 
Ignores the contents of the volume header 
record. You cannot use this flag if the 
BCK_OPTYP_K_EXACT_ORDER option 
structure flag value is TRUE. 
BCK_OPTYP_IGNORE_K NOBACKUP 
Processes both the file header and 
the contents of files marked with the 
NOBACKUP option. 


(See the BACKUP qualifier /\GNORE.) 

Flag that directs that an entire volume or volume 
set be processed. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /IMAGE.) 

Flag that specifies whether to restore an 
incremental save set. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /INCREMENTAL.) 
Flag that specifies whether to initialize an entire 
output volume, thereby making its previous 
contents inaccessible. 

Values are TRUE and FALSE (default, except for 
image restore and copy operations). 

(See the BACKUP qualifier /INITIALIZE.) 

32-bit descriptor that specifies a single input- 
specifier. You can use wildcards. You must use a 
separate BCK_OPT_K_INPUT option structure 
for each specification. 

(See the BACKUP Format description.) 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_INTERCHANGE 


BCK_OPT_K_J OURNAL 


BCK_OPT_K_J OURNAL_FILE 


BCK_OPT_K_LABEL 


BCK_OPT_K_LIST 


BCK_OPT_K_LIST FILE 


BCK_OPT_K_LOG 


Flag that specifies whether to process files in a 
manner suitable for data interchange. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier A NTERCHANGE.) 
Flag that specifies whether a BACKUP journal 
file is to be processed. You can specify a journal 
file name other than BACKUP.B] L (the default) 
with the BCK_OPT_K_J OURNAL_FILE option 
structure. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /) OURNAL.) 

32-bit descriptor that specifies the name of a 
BACKUP journal file to be processed. 

(See the BACKUP qualifier /) OURNAL.) 

32-bit descriptor that specifies the volume label 
to be written. To specify more than one label, 
use additional BCK_OPT_K_LABEL option 
structures. 

(See the BACKUP qualifier /LABEL.) 

Note: Use of BCK_OPT_K_LABEL with any 
BCK_OPT_K_ SCRATCH _* option structure in 
the same call results in a fatal error. 

Flag that specifies whether to process a 
BACKUP list file. You can specify a list output 
destination other than TTY: (the default) with the 
BCK_OPT_K_LIST_ FILE option structure. 
Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /LIST.) 

32-bit descriptor that specifies the name of a file 
of a BACKUP journal file to be processed. 

(See the BACKUP qualifier /LIST.) 

Flag that specifies whether to display the file 
specification of each file processed. The display is 
to SYS$OUTPUT. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /LOG.) 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_MEDIA_FORMAT 


BCK_OPT_K_MODIFIED 


BCK_OPT_K_NEW_VERSION 


BCK_OPT_K_OPERATION_TYPE 
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Logical bit flags that specify whether data 
records are automatically compacted and 
blocked together. The tape drive must support 
compaction. 

Values are one of the following: 


BCK_OPTYP_MEDIA_K_COMPACTION 
BCK_OPTYP_MEDIA_K_NO COMPACTION 
(default) 


(See the BACKUP qualifier /MEDIA_FORMAT.) 


Note: Use of BCK_OPT_K_MEDIA_FORMAT 
and BCK_OPT_K_DENSITY in the same call 
results in a fatal error. 


Flag that specifies whether to select files 
according to the modification date written in 
the file header record. 

Values are TRUE and FALSE. 

Use this flag to set the corresponding logical 

bit flag for BCK_OPT_K_BEFORE_TYPE and 
BCK_OPT_K_SINCE_TYPE. 

(See the BACKUP qualifiers /BEFORE, /SINCE, 
and /MODIFIED.) 


Flag that specifies whether to create a new 
version of a file if a file with an identical file 
specification already exists at the location to 
which the file is being copied or restored. 

Values are TRUE and FALSE (default). 

Because this qualifier causes version numbers to 
change, using it with the BCK_OPT_K_VERIFY 
flag set to TRUE can cause unpredictable results. 
HP recommends that you not use these two 
options in combination. 

(See the BACKUP qualifier /NEW_VERSION.) 


Logical bit flags that specify the type of BACKUP 
operation to be performed. 
Values are one of the following: 


BCK_OP_K_SAVE (default) 
BCK_OP_K_RESTORE 
BCK_OP_K_COPY 
BCK_OPT_K_LIST 
BCK_OPT_K_COMPARE 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_OUTPUT 


BCK_OPT_K_OVERLAY 


BCK_OPT_K_OWNER_IN VALUE 


BCK_OPT_K_OWNER_OUT_TYPE 


32-bit descriptor that specifies the name of a 
single output-specifier. You can use wildcards. 
Each file specification requires a separate 
BCK_OPT_K OUTPUT option structure. Lists 
are not supported. 

(See BACKUP Format description.) 

Flag that specifies whether to overlay (at the 
same physical location) an existing file with a file 
specification identical to that of the file that is 
being copied or restored. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /OVERLAY.) 

Integer that specifies the user identification code 
(UIC) of the files to be processed by a BACKUP 
input operation. The default is the UIC of the 
current process. If you do not include this option 
structure, BACKUP processes all files specified 
by BCK_OPT_K_INPUT. 

(See the BACKUP qualifier /BY_OWNER.) 


Logical bit flags to specify the user identification 
code (UIC) of restored files. 
Values are one of the following: 
BCK_OPTYP_OWN_OUT_K_DEFAULT 
Sets the owner UIC to the VIC of the current 
process (default unless BCK_OPT_K_IMAGE 
or BCK_OPT_K_INCREMENTAL is TRUE). 


BCK_OPTYP_OWN_OUT_K_ORIGINAL 


Retains the owner UIC of the file being 
restored (default if BCK_OPT_K_IMAGE or 
BCK_OPT_K_INCREMENTAL is TRUE). 
BCK_OPTYP_OWN_OUT_K_ PARENT 
Sets the owner UIC to the owner UIC of the 
directory to which the file is being written. 
The current process must have the SYSPRV 
user privilege, or be the owner of the output 
volume, or must have the parent UIC. 


(See the BACKUP qualifier /BY_OWNER.) 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_OWNER_OUT_ VALUE 


BCK_OPT_K_PHYSICAL 


BCK_OPT_K_PROTECTION 


BCK_OPT_K_RECORD 
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Integer that redefines the UIC of the files written 
by a BACKUP restore or copy operation, or 
specifies the UIC of an output save set. 

If BCK_OPT_K OUTPUT specifies a save set, 
the default is the UIC of the current process. To 
specify the UIC of a Files-11 save set, the current 
process must have the SYSPRV user privilege, or 
must have the UIC specified. 

If BCK_OPT_K OUTPUT specifies files, the UIC 
of the output files is set to the UIC specified. To 
specify the UIC, the UIC must be that of the 
current process, or must have the SYSPRV user 
privilege, or the current process must be the 
owner of the output device. 

(See the BACKUP qualifier /BY_ OWNER.) 


Flag that specifies that a BACKUP operation is 
to ignore any file structure on the input volume 
and instead process the volume in terms of logical 
blocks. 

Values are TRUE and FALSE (default). Note 
that output operations on a save set must be 
performed with the same physical option as that 
used to create the save set. (See the BACKUP 
qualifier /PHYSICAL.) 

Note: Use of BCK_OPT_K_PHYSICAL and 
BCK_OPT_K_UNSHELVE or BCK_OPT_K_ 
ALIAS in the same call results in a fatal error. 
Logical bit flags that specify file protection. Bits 0 
to 15 of the option structure value field are in the 
format of the RMS field XAB$W_PRO. See the 
OpemVMS Record Management Services Reference 
Manual for information about the format of this 
field. 

(Also see BACKUP utility qualifier 
/PROTECTION.) 

Flag that specifies whether to record the current 
date and time in the BACK UP date field in each 
file header once a file is successfully saved or 
copied. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /RECORD.) 


(continued on next page) 


Backup API 
BACKUP$START 


Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_RELEASE_TAPE 


BCK_OPT_K_REPLACE 


BCK_OPT_K_REWIND 
BCK_OPT_K_REWIND_IN 


BCK_OPT_K_REWIND_OUT 


BCK_OPT_K_SAVE_SET_IN 


BCK_OPT_K_SAVE_SET_OUT 


Flag that specifies whether to dismount and 
unload a tape after a BACKUP save operation 
has either reached the end of the tape or has 
written and verified the save set. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier (RELEASE TAPE.) 
Flag that specifies whether to replace (at a 
different physical location), with an identical 
version number, an existing file with a file 
specification identical to that of the file that 

is being copied or restored. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /REPLACE.) 

Flag. Reserved for use by HP. 

Flag that specifies whether the input device is 
a tape drive, and that it is to be rewound to the 
beginning-of-tape marker before beginning the 
BACKUP operation. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /REWIND.) 

Flag that specifies whether the output device is 
a tape drive, and that it is to be rewound to the 
beginning-of-tape marker and initialized before 
beginning the BACKUP operation. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /REWIND.) 

Note: Use of BCK_OPT_K_REWIND_OUT with 
any BCK_OPT_K_SCRATCH _* option structure 
in the same call results in a fatal error. 

Flag that indicates whether the input specifier is 
a BACKUP save-set file. 

Values are TRUE and FALSE (default; indicates 
that the input specifier refers to a Files-11 file). 
(See the BACKUP qualifier /SAVE_SET.) 

Flag that indicates whether the output specifier 
specifies a BACKUP savesset file. 

Values are TRUE and FALSE (default; indicates 
that the output specifier refers to a Files-11 file). 
(See the BACKUP qualifier /SAVE_SET.) 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_SCRATCH_ASGN_TYPE ! 


BCK_OPT_K_SCRATCH COLLECTION ? 


BCK_OPT_K_SCRATCH LOCATION ! 


BCK_OPT_K_SCRATCH_MEDIA_NAME 1 


BCK_OPT_K_SELECT 


Logical bit flags. 

Note: Use of BCK_OPT_K SCRATCH _ASGN _ 
TYPE with BCK_OPT_K_LABEL, BCK_OPT_ 
K_REWIND_OUT, any of the BCK_OPT_K_ 
CARTRIDGE_* option structures, or any other 
BCK_OPT_K_ SCRATCH _* option structure in 
the same call results in a fatal error. 

32-bit descriptor. 

Note: Use of BCK_OPT K_SCRATCH_ 
COLLECTION with BCK_OPT_K_LABEL, BCK_ 
OPT_K_REWIND_OUT, any of the BCK_OPT_K_ 
CARTRIDGE_* option structures, or any other 
BCK_OPT_K_ SCRATCH _* option structure in 
the same call results in a fatal error. 

32-bit descriptor. 

Note: Use of BCK_OPT_K_SCRATCH_ 
LOCATION with BCK_OPT_K_LABEL, BCK_ 
OPT_K_REWIND_OUT, any of the BCK_OPT_K_ 
CARTRIDGE_* option structures, or any other 
BCK_OPT_K_ SCRATCH _* option structure in 
the same call results in a fatal error. 

32-bit descriptor. 

Note: Use of BCK_OPT_K_ SCRATCH _MEDIA_ 
NAME with BCK_OPT_K_LABEL, BCK_OPT_ 
K_REWIND_OUT, any of the BCK_OPT_K_ 
CARTRIDGE_* option structures, or any other 
BCK_OPT_K_ SCRATCH _* option structure in 
the same call results in a fatal error. 


32-bit descriptor that references the file 
specification of a file or files from the input save 
set to be processed by the current BACKUP save 
or copy operation. Wildcards are permitted. Each 
file specification, whether wildcards are used 

or not, requires its own BCK_OPT_K_SELECT 
option structure (lists are not supported). 


(See the BACKUP qualifier /SELECT.) 


1Reserved for use by Media Management Extension (MME) layered products. 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure 


Description 


BCK_OPT_K_SINCE_TYPE 


BCK_OPT_K_SINCE_VALUE 


BCK_OPT_K_STORAGE_MANAGEMENT 
BCK_OPT_K_TAPE_EXPIRATION 


BCK_OPT_K_TRUNCATE 


Logical bit flags that qualify the date specified 
in the BCK_OPT_K_SINCE_VALUE option 
structure. 
Type can be one of the following: 
BCK_OPTYP_SINCE_K_BACKUP 
Selects files last saved or copied by BACKUP 
on or after the date specified. Also selects 
files with no BACKUP date. 
BCK_OPTYP_SINCE_K_CREATED 
Selects files created on or after the date 
specified. 
BCK_OPTYP_SINCE K_EXPIRED 
Selects files that have expired since the date 
specified. 
BCK_OPTYP_SINCE_K_ MODIFIED 
Selects files last modified on or after the date 
specified (default). 
BCK_OPTYP_SINCE_K_SPECIFIED 
Reserved for use by HP. 


(See the BACKUP qualifiers /SINCE, /BACKUP, 
/CREATED, /EXPIRED, and /MODIFIED.) 
Date-Time Quadword that specifies the date 
qualified by BCK_OPTYP_K_SINCE_TYPE. You 
cannot use delta time. 

(See the BACKUP qualifier /SINCE.) 

32-bit descriptor. 


ADT (Date-Time) that specifies when the tape 
expires. 

(See the BACKUP qualifier /TAPE_ 
EXPIRATION.) 

Flag that specifies whether a copy or restore 
operation truncates a sequential output file at the 
end-of-file (EOF ) when creating it. 

Values are TRUE and FALSE (default; the size of 
the output file is determined by the allocation of 
the input file). 

(See the BACKUP qualifier /TRUNCATE.) 


1Reserved for use by Media Management Extension (MME) layered products. 
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Table 3—2 (Cont.) BACKUP Option Structure Types 


Option Structure Description 


BCK_OPT_K_UNSHELVE Flag that is reserved for use with fileshelving 


layered products. 
Values are TRUE and FALSE. 


Note: Use of BCK_OPT_K_UNSHELVE and 
BCK_OPT_K_PHYSICAL in the same call results 
in a fatal error. 


BCK_OPT_K_VALIDATE_PARAMETERS Reserved for use by HP. 
BCK_OPT_K_VERIFY Flag that specifies whether the contents of the 


output specifier be compared with the contents of 
the input specifier after a save, restore, or copy 
operation has been completed. 

Values are TRUE and FALSE (default). 

(See the BACKUP qualifier /VERIFY.) 


BCK_OPT_K_VOLUME Integer that specifies the specific disk volume in a 


disk volume set to be processed (valid only when 
BCK_OPT_K_IMAGE is TRUE). 


(See the BACKUP qualifier VOLUME.) 


Description 


Application programs call the Backup API to invoke the OpenVMS Backup utility 
via a call to the BACKUP$START routine. There is only one parameter, the 
address of an argument buffer that contains a number of option structures that 
together define the operation requested of the Backup utility. Most of these option 
structures are equivalent, singly or in combination, to the qualifiers available 
when invoking the BACKUP utility with the DCL command BACKUP; the call 

to the API is analogous to a user entering an interactive command to the Backup 
utility. 


The call to BACKUP$START is synchronous; that is, it does not return until the 
operation is complete or is terminated by a fatal error. In the case of a fatal error, 
the call is aborted. 


BACKUP Event Callbacks 


An application can request that the BACKUP API notify the application whenever 
specific events occur. The application can specify different callback routines to 
handle different types of BACKUP events, or one routine to handle all events. To 
do so, the application registers the callback routine by including option structure 
BCK_OPTYP_K_EVENT_ CALLBACK in the call to BACKUP$START. This 
option structure specifies an event type (or all events) and the address of a 
routine to be called when the event occurs. The application must include one 
such option structure for each requested event type. To specify all events, use 
BCK_EVENT_K_ALL. Table 3-4 lists the specific event types and identifiers. 


A callback routine: 


e Is called with one argument; a pointer to a bckEvent data structure that 
contains information to enable the application to process the event 
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e Returns an unsigned integer status value (of any valid OpenVMS message) in 
RO to enable the API to perform proper logging of the event 


Note 


The API does not currently process the return status of the callback 
routine. However, HP strongly recommends that the callback routine 
provide the appropriate status in RO when returning control to the API. 


The bckE vent structure contains information about the type of event, and also 
contains a descriptor of a data structure that contains information to be used to 
process the event. The bckEvent structure may point to a bckControl structure 
that specifies control aspects of an event that may require user or operator action. 


Table 3-3 describes the format of the bckEvent data structure. Table 3-6 
describes the format of the bckControl data structure. 


Table 3-3 bckEvent Format 


Data Type Element Name 


Description 


struct dsc$descriptor bckevt_r_event_buffer 


unsigned int bckevt_l_event_type 
unsigned int bckevt_I_event_subtype 
unsigned int bckevt_q_event_ctx [2] 
unsigned int bckevt_l_event_handle 


Pointer to event data 
Event type 

Event subtype (if any) 
Reserved for use by HP 
Reserved for use by HP 


Table 3-4 describes the values returned in the bckEvent data structure. 


Table 3-4 Event Callback Buffer Formats 


Type/Subtype Format Value Returned 
BCK_EVENT_K_CONTROL bckControl See Table 3-5. 
BCK_EVENT_ K_ERROR_MSG 

(no subtype) bckM sgVect Message vector (use $PUTMSG to 


BCK_EVENT_K_J OURNAL_OPEN 


(no subtype) dsc$descri ptor 


BCK_EVENT_K_J OURNAL_CLOSE 


(no subtype) dsc$descri ptor 


BCK_EVENT_K_J OURNAL_WRITE 


(no subtype) 512-byte block 


output message to user). 


String descriptor (name of file to 
create). 


String descriptor (name of file to 
close). 


File descriptor of journal buffer 
(condensed journal records, refer to 
the BJ LDEF structure definition in 
the BAPIDEF files). 


(continued on next page) 
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Table 3—4 (Cont.) Event Callback Buffer Formats 


Type/Subtype Format Value Returned 
BCK_EVENT K_LIST CLOSE 
(no subtype) Array of 2 LIST TOTFILE: Total files listed. 
longwords LIST_TOTSIZE: Total blocks listed. 
Note: The application should close 
the list file. 
BCK_EVENT K_LIST_OPEN 
TRUE dsc$descri ptor File specification of list file to open 
(TRUE =1, indicates /FULL listing). 
FALSE dsc$descri ptor (FALSE =0). 
BCK_EVENT_K_LIST_WRITE 
BRH$K_SUMMARY BSRBLK List BACKUP save set - save set 
summary record. 
BRH$K_VOLUME BSRBLK List BACKUP save set - volume 
summary record. 
BRH$K_PHYSVOL PVABLK List BACKUP save set - physical 
volume record. 
BRH$K_FILE FARBLK List BACKUP save set - file record. 
BCK_EVENT K_LISTJ OUR_WRITE Subtype is a condition value that 


indicates the type of action that 
occurred for the specified file/item. 
Obtain message text with the 
$GETMSG system service. 


TRUE bckLis} ourblk J ournal file listing information (TRUE 
=1, indicates a change of volume or 
save Set). 

FALSE dsc$descri ptor J ournal file listing of filefitem 
specification string (descriptor) 
(FALSE =O). 

BCK_EVENT K_LOG 

BACKUP$ AECREATED dsc$descri ptor String descriptor (file logging). 

BACKUP$ COMPARED dsc$descri ptor String descriptor (file logging). 

BACKUP$ COPIED dsc$descri ptor String descriptor (file logging). 

BACKUP$ CREATED dsc$descri ptor String descriptor (file logging). 

BACKUP$ CREDIR dsc$descri ptor String descriptor (file logging). 

BACKUP$ HEADCOPIED dsc$descri ptor String descriptor (file logging). 

BACKUP$ INCDELETE dsc$descri ptor String descriptor (file logging). 

BACKUP$ NEWSAVSET dsc$descri ptor String descriptor (file logging). 


BCK_EVENT_K_OP_PHASE 


BACKUP$ STARTVERIFY Condition Value Start of verify operation (obtain 
message text with $GETMSG). 
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Type/Subtype 


Format 


Value Returned 


BACKUP$ STARTDELETE 
BACKUP$ STARTRECORD 


BCK_EVENT_K_ SAVESET CLOSE 
(no subtype) 

BCK_EVENT_K_SAVESET_OPEN 
(no subtype) 


BCK_EVENT_K_SAVESET_READ 
(no subtype) 


BCK_EVENT_K_SAVESET_WRITE 
(no subtype) 


BCK_EVENT_K_STATISTICS 
(no subtype) 


BCK_EVENT_K_USER_MSG 
(no subtype) 


Condition Value 


Condition Value 


RMS FOB 


RMS FOB 


BACKUP Buffer 
Control Block 
(BCBBLK) 


BACKUP Buffer 
Control Block 
(BCBBLK) 


bckM sgVect 


bckM sgVect 


Start of delete operation (obtain 
message text with $GETMSG). 


Start of record operation (obtain 
message text with $GETMSG). 


A BACKUP save set must be closed. 


A BACKUP save set must be opened 
or created. 


A BACKUP save set block/buffer has 
been read from the input save set. 


A BACKUP save set block/buffer is 
ready to be written to the output save 
set. 


Statistics message; one of the 
following message condition values 
(use $PUTMSG to output message to 
user): 


BACKUP$ STAT_PHYSICAL 
BACKUP$ STAT_SAVCOP_ACT 
BACKUP$ STAT_INACTIVE 
BACKUP$ STAT_COMPARE 
BACKUP$ STAT_RESTORE 


Message vector (use $PUTMSG to 
output message to user). 
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Table 3-5 describes the control event subtypes of the BCK_EVENT_K_ CONTROL 
event callback. Table 3-6 describes the format of the bckControl data structure. 


Table 3-5 Control Event Subtypes 


Format 
Subtype Field Description 
Confirmation is required for compare or copy 
BCKEVTST_K_CONFIRM_EVENT operation. 
bckCntrl_l_event BCKCNTRL_K_CONFIRM_EVENT 
bckCntrl_|_ function Backup operation type (integer value) 
bckCntrl_a_outmsgvect Confirmation message (bckMsgVect, 


BACKUP$ CNTRL_CONFCOMP or 
BACKUP$ CNTRL_CONFCOPY) 


bckCntrl_v_response_ required TRUE (response is required) 
bckCntrl_r_response_buffer dsc$descriptor ("Yes/No" string descriptor) 


Operator or user assistance is required to 


BCKEVTST_K_ASSIST_EVENT determine continuation/actions. 
bckCntrl_l_ event BCKCNTRL_K_USER_ASSIST_EVENT or 
BCKCNTRL_K_OPER_ASSIST EVENT 
bckCntrl_|_ function Backup operation type (integer value) 
bckCntrl_a_outmsgvect bckMsgVect (assist and other messages) 
bckCntrl_v_response_ required TRUE or FALSE (TRUE =1, if response is 
required) 
bckCntrl_r_response_buffer dsc$descriptor (response string descriptor) 
BCKCNTRL_K_RESTART_EVENT BACKUP operation restart is initiated. 
bckCntrl_|_event BCKCNTRL_K_RESTART_EVENT 
bckCntrl_|_ function Backup operation type (integer value) 
bckCntrl_a_outmsgvect bckMsgVect (operation restart message vector) 
bckCntrl_v_response_ required FALSE (=0, no response is required) 
bckCntrl_r_response_buffer dsc$descriptor ("Yes/No" string descriptor) 
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Control events are described by the Control event subtype, via the bckevt_l_ 
event_subtype field in the bckEvent structure. Table 3-6 describes the format of 
the bckControl data structure. 


Table 3-6 bckControl Format 


Data Type 


Element Name 


Description 


unsigned int 
unsigned int 
bckM sgVect 


union { 
unsigned int 
struct { 
unsigned 


unsigned 
} 


struct dsc$descriptor 


unsigned int 
unsigned int 


bckCntrl_l_event 
bckCntrl_l_ function 
*bckCntrl_a_outmsgvect 


bckCntrl_|_ctlflags 
bckCntrl_v_response required 
:1 

bckCntrl_v_fill_5: 7 
bckCntrl_r_response_buffer 


bckCntrl_|_response_status 
bckCntrl_l_control_options 


Control event type. 
Backup operation type. 
Output messages and 
parameters. 


Flags. 

Response required =1. 

Filler. 

Descriptor for buffer to which 
response text is to be written. 


Reserved for use by HP. 
Reserved for use by HP. 


Error Messages 


Where possible, the Backup API emulates the behavior of the interactive 
BACKUP utility if you pass a call that contains conflicting qualifiers by: 


1. Making a best guess as to your intentions 


2. Ignoring the least likely of the conflicting qualifiers 


3. Issuing a message that warns of the conflicting qualifiers 


4. Processing the BACKUP request 


See the HP OpenVMS Systen Management Utilities Reference Manual: A-L for a 
table of valid combinations of BACKUP qualifiers. 


Condition Values Returned 


SS$ NORMAL 

BACKUP$ BADOPTDSC 
BACKUP$ BADOPTTYP 
BACKUP$ BADOPTVAL 
BACKUP$ BADOPTVALQ 
BACKUP$ DUPOPT 


Normal successful completion. 

Invalid callable interface option descriptor. 
Invalid callable interface option type. 

Invalid callable interface option value. 

Invalid callable interface option value. 
Previously specified callable interface option type 
invalid. 

Callable interface required parameter not 
specified or invalid. 


BACKUP$ NOAPIARGS 


Any condition value returned by the OpenVMS Backup utility. 
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Example 


The following C example program demonstrates calling the Backup API to 
perform the following DCL commands: 


$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_IN:*.*;* - 
_$ APITEST1_OUT:A.BCK/SAVE_SET 


$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1 OUT:A.BCK/SAVE SET - 
_$ APITEST2 OUT:*.*;* 


#include <stdio.h> 

#include <stdlib.h> 

#include <ssdef.h> 

#include <descrip.h> 

#include "sysSexamples:bapidef.h" 


/* 

** Define a fixed size (simple) structure for specifying the 
** BACKUP operation. 

gi 

typedef struct buf _arg 


bck_opt_struct_flag argl; 
bck opt _struct_flag arg2; 
bck opt _struct_flag arg3; 
beck opt _struct_flag arg4; 
bck opt _struct_dsc arg5; 
bck opt _struct_dsc arg6; 
beck opt _struct_flag arg7; 
bck opt _struct_flag arg8; 
bck opt _struct_adr arg9; 
bck opt _struct_adr argl0; 
bck opt _struct_adr argll; 
bck opt_struct_flag argl2; 
bck opt_struct_flag argl3; 
} buf_arg; 


struct dsc$descriptor 
input_dsc, 
output_dsc, 
event_type_ dsc; 

buf_arg myarg buff; 

unsigned int status; 


extern unsigned int backupSstart (buf arg *myarg buff) ; 
unsigned int subtest (bckEvent *param) ; 


static char input_str[] = "APITEST1 IN:"; 

static char output_strl[] = "APITEST1 OUT:a.bck"; 
static char output_str2[] = "APITEST2 OUT:"; 
main () 


myarg buff.argl.option_type = BCK_OPT K ALIAS; 
myarg buff.argl.opt_ flag value = TRUE; 


myarg buff.arg2.option_type = BCK_OPT K VERIFY; 
myarg buff.arg2.opt_flag_ value = TRUE; 


myarg buff.arg3.option_type = BCK_OPT K CRC; 
myarg buff.arg3.opt_flag_ value = TRUE; 
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3 


yarg buff.arg4.option_type = BCK OPT K LOG; 
myarg buff.arg4.opt_flag_value = TRUE; 


3 


yarg buff.arg5.opt_dsc_type = BCK OPT K INPUT; 

yarg buff.arg5.opt_dsc.dsc$b dtype = DSCSK_DTYPE T; 

yarg buff.arg5.opt_dsc.dsc$b class = DSCSK CLASS S$; 
myarg_buff.arg5.opt_dsc.dsc$w length = sizeof(input_str) - 1; 
myarg buff.arg5.opt_dsc.dsc$a_pointer = input_str; 


3 


myarg_buff.argé.opt_dsc_type = BCK_OPT K OUTPUT; 
yarg buff.argé.opt_dsc.dsc$b dtype = DSCSK DTYPE T; 
myarg_buff.argé.opt_dsc.dsc$b class = DSCS$K CLASS S; 
myarg_buff.argé.opt_dsc.dsc$w_length = sizeof(output_strl) - 1; 
yarg buff.argé.opt_dsc.dsc$a_pointer = output_str1; 
myarg buff.arg7.option_type = BCK_OPT K SAVE SET OUT; 
yarg buff.arg7.opt_ flag value = TRUE; 
myarg_ buff.arg8.option_ type = BCK OPT K OPERATION TYPE; 
yarg buff.arg8.opt flag value = BCK_OP K SAVE ; 
myarg buff.arg9.opt_adr_type = BCK_OPT K EVENT CALLBACK; 
yarg buff.arg9.opt_adr_ attributes = BCK EVENT K LOG; 


3 


yarg buff.arg9.opt adr value[0] = (int *) subtest; 
yarg buff.arg9.opt_adr value[1] = 0; 


3 


/* 

** Specify that this application will handle user-visible messages. 
** (The operation phase, and user/file-logging messages.) 

* 

/ 

yarg buff.argl0.opt_adr_type = BCK_OPT K EVENT CALLBACK; 

yarg buff.argl0.opt_adr_ attributes = BCK_EVENT K OP PHASE; 

myarg buff.argl10.opt_adr_value[0] = (int *)subtest; 

myarg buff.argl10.opt_adr_value[1] = 0; 


3 


yarg buff.argll.opt_adr_type = BCK_OPT K EVENT CALLBACK; 
yarg buff.argll.opt_adr_attributes = BCK EVENT K USER MSG; 
myarg buff.argll.opt_adr_value[0] = (int *)subtest; 

yarg buff.argll.opt_adr_value[1] = 0; 


3 


/* 

** Indicate the end of options that specify the BACKUP operation 
** to be performed. 

| 

myarg_buff.argl2.option_type = BCK OPT K END OPT; 

myarg_ buff.argl2.opt_flag_ value = FALSE; 

/* 

** Notes: 

** An extra option structure (# 13) was allocated for testing. 
kK 

** The DCL command analogous to the following BACKUP API call 
** is illustrated below. 

kK 

** "§ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_IN:*.*;* -" 

** " § APITEST1 OUT:a.bck/SAVE SET " 


*/ 
status = backupSstart (&myarg_buff) ; 
if (! (status & 1)) 
{ 
exit (status); /* EXIT if the first part of the test failed. */ 
} 
/* 


** Now use the resultant saveset to perform a restore operation. 
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/* 
** Change the input string to specify the saveset, ("output_str1"). 
a7 


myarg_buff.arg5.opt_dsc.dsc$w_length = sizeof(output_str1) - 1; 
myarg_ buff.arg5.opt_dsc.dsc$a_pointer = output_strl; 


/* 

** Change the output string to specify the output device/directory) . 
ei 

myarg_ buff.arg6.opt_dsc.dsc$w_ length = sizeof(output_str2) - 1; 
myarg buff.argé.opt_dsc.dsc$a_pointer = output_str2; 

/* 

** Change the option to denote it is now an input saveset, 

** (not an output saveset). 

| 


myarg buff.arg7.option_ type = BCK OPT K SAVE SET IN; 


/* 

** Change the option to specify a restore operation, 

** (not a save operation). 

*/ 

myarg buff.arg8.opt_flag_ value = BCK_OP K RESTORE; 

/* 

** The DCL command analogous to the following BACKUP API call 


** is illustrated below. 
kk 


** "S$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_OUT:a.bck/SAVE_SET al 
** " S$  APITEST2 OUT:*.*;*" 
*/ = a 
status = backupSstart (&myarg_buff) ; 
exit (status) ; 


} 


unsigned int subtest (bckEvent *param) 


printf ("\n BACKUP API Event Type = %d,\n",param->bckevt_1_ event_type) ; 
printf (" Subtype = %d\n",param->bckevt_1 event _subtype) ; 


if (param->bckevt_l_event_type == BCK_EVENT_K_ LOG) 
printf (" BACKUP API LOG Event item:\n %.*s\n", 


param->bckevt_r_event_buffer.dsc$w_length, 
param->bckevt_r_event_buffer.dsc$a_pointer) ; 


} 


if (param->bckevt_l event_type == BCK EVENT K OP PHASE) 
printf(" BACKUP API Operation Phase Event\n %.*s\n", 


param->bckevt_r_event_buffer.dsc$w_length, 
param->bckevt_r_event_buffer.dsc$a_pointer) ; 


fflush(stdout) ; 


return (1); 
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Command Language Interface (CLI) Routines 


The command language interface (CLI) routines process command strings 

using information from a command table. A command table contains command 
definitions that describe the allowable formats for commands. To create or modify 
a command table, you must write a command definition file and then process 
this file with the Command Definition Utility (the SET COMMAND command). 
For information about how to use the Command Definition Utility, see the 

HP OpenVMS Command Definition, Librarian, and Message Utilities Manual. 


4.1 Introduction to CLI Routines 
The CLI routines include the following: 
e CLI$DCL_PARSE 
« CLI$DISPATCH 
e CLI$GET VALUE 
e CLI$PRESENT 


When you use the Command Definition Utility to add a new command to your 
process command table or to the DCL command table, use the CLISPRESENT 
and CLI$GET_ VALUE routines in the program invoked by the new command. 
These routines retrieve information about the command string that invokes the 
program. 


When you use the Command Definition Utility to create an object module 
containing a command table and you link this module with a program, you must 
use all four CLI routines. First, use CLI$DCL_PARSE and CLI$DISPATCH 

to parse command strings and invoke routines. Then, use CLISPRESENT and 
CLI$GET_ VALUE within the routines that execute each command. 


Note that the application program should declare referenced constants and return 
status symbols as external symbols; these symbols are resolved upon linking with 
a utility shareable image 


A CLI must be present in order to use the CLI routines. If your application 
can be run from a detached process, the application should first verify that a 
CLI exists. For information about how to verify that a CLI exists for a process, 
see the description of the $GETJ PI system service in the HP OpenVMS Systen 
Services Reference Manual. 


Note 


Do not use the CLI routines to obtain values from foreign commands. 
Using a foreign command to activate an image (instead of the SET 
COMMAND command) disrupts the building of the DCL parse tables. 


Command Language Interface (CLI) Routines CLI-1 


Command Language Interface (CLI) Routines 
4.2 Using the CLI Routines: An Example 


4.2 Using the CLI Routines: An Example 


Example 4-1 contains a command definition file (SUBCOMMANDS.CLD) and a 
Fortran program (INCOME.FOR). INCOME.FOR uses the command definitions 
in SUBCOMMANDS.CLD to process commands. To execute the example, enter 
the following commands: 


$ SET COMMAND SUBCOMMANDS /OBJECT=SUBCOMMANDS 
$ FORTRAN INCOME 

$ LINK INCOME, SUBCOMMANDS 

$ RUN INCOME 


INCOME.FOR accepts a command string and parses it using CLI$DCL_PARSE. 
If the command string is valid, the program uses CLI$DISPATCH to execute the 
command. Each routine uses CLISPRESENT and CLI$GET_VALUE to obtain 
information about the command string. 


Example 4-1 Using the CLI Routines to Retrieve Information About Command 
Lines in a Fortran Program 


KRKEKKK EKER KEKE KERR EKER KEKE K RK KERR EKER KEKE RRR KERR KEKE KERR KEKE KEKE 


SUBCOMMANDS . CLD 


KHREKEKKK KKK KKK KKK KEKE KKK KR KKK RR KE RRR RRR KERR KEKE RR KKEKRKEKKEKEEKE 


ODULE INCOME SUBCOMMANDS 


DEFINE VERB ENTER 
ROUTINE ENTER 


DEFINE VERB FIX 
ROUTINE FIX 
QUALIFIER HOUSE NUMBERS, VALUE (LIST) 


DEFINE VERB REPORT 

ROUTINE REPORT 

QUALIFIER OUTPUT, VALUE (TYPE = SFILE, 

DEFAULT = "INCOME.RPT") 
DEFAULT 


KHREKEKKK KKK EKER KKK KEK KEKE KERR KERR EKER KEKE RRR KERR KEK KK KEKE KKEKEKE 


INCOME. FOR 
FOI III RR kok 
PROGRAM INCOME 
INTEGER STATUS, 

2 CLISDCL_PARSE, 

2 CLISDISPATCH 
INCLUDE ' ($RMSDEF) ’ 

INCLUDE ' (SSTSDEF) ’ 

EXTERNAL INCOME SUBCOMMANDS , 
2 LIBSGET_INPUT 


(continued on next page) 
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Example 4-1 (Cont.) Using the CLI Routines to Retrieve Information About 
Command Lines in a Fortran Program 


! Write explanatory text 
STATUS = LIBSPUT_OUTPUT 
2 ('Subcommands: ENTER - FIX - REPORT’) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
STATUS = LIBSPUT_OUTPUT 

2 (’Press Ctrl/Z to exit’) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! Get first subcommand 
STATUS = CLISDCL_ PARSE (SVAL (0), 


2 INCOME SUBCOMMANDS, ! CLD module 

2 LIBSGET_INPUT, ! Parameter routine 
2 LIBSGET_INPUT, ! Command routine 

2 'INCOME> ') ! Command prompt 


! Do it until user presses Ctr1/Z 
DO WHILE (STATUS .NE. RMS$ EOF 
! If no error on dcl_ parse 
IF (STATUS) THEN 
! Dispatch depending on subcommand 
STATUS = CLISDISPATCH () 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 

! Do not signal warning again 

ELSE IF (IBITS (STATUS, 0, 3) .NE. STSSK WARNING) THEN 
CALL LIBSSIGNAL (VAL (STATUS) ) 

END IF 

! Get another subcommand 
STATUS = CLISDCL PARSE (%VAL (0), 


2 INCOME SUBCOMMANDS, ! CLD module 

2 LIBSGET_INPUT, ! Parameter routine 
2 LIBSGET_ INPUT, ! Command routine 

2 "INCOME> ') ! Command prompt 
END DO 

END 


INTEGER FUNCTION ENTER () 
INCLUDE ' (SSSDEF) ' 
TYPE *, ‘ENTER invoked’ 
ENTER = SS$ NORMAL 
END 


INTEGER FUNCTION FIX () 
INTEGER STATUS, 
2 CLISPRESENT, 

2 CLISGET_VALUE 
CHARACTER*15 HOUSE NUMBER 
INTEGER* 2 HN SIZE 
INCLUDE ' (SSSDEF) ' 
EXTERNAL CLI$ ABSENT 
TYPE *, ‘FIX invoked’ 
! If user types /house numbers=(n,...) 
IF (CLISPRESENT (‘HOUSE NUMBERS’ ) ) THEN 
! Get first value for /house numbers 
STATUS = CLISGET_VALUE (‘HOUSE NUMBERS’ , 
2 HOUSE NUMBER, 
2 HN SIZE) 


(continued on next page) 
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Example 4-1 (Cont.) Using the CLI Routines to Retrieve Information About 
Command Lines in a Fortran Program 


! Do it until the list is depleted 
DO WHILE (STATUS) 


TYPE *, ‘House number = ’, HOUSE NUMBER (1:HN_ SIZE) 
STATUS = CLISGET_ VALUE (‘HOUSE NUMBERS’ , 

2 HOUSE NUMBER, 
2 HN SIZE) 

END DO 

! Make sure termination status was correct 
IF (STATUS .NE. %LOC (CLI$_ ABSENT) ) THEN 
CALL LIBSSIGNAL (VAL (STATUS) ) 

END IF 

END IF 

FIX = SSS NORMAL 

END 

INTEGER FUNCTION REPORT () 

INTEGER STATUS, 


iS) 


CLISGET_ VALUE 
CHARACTER*255 FILENAME 

INTEGER*2 FN SIZE 

INCLUDE ' (SSSDEF) ’ 

TYPE *, ‘REPORT entered’ 

! Get value for /output 

STATUS = CLISGET VALUE ('OUTPUT’, 


2 FILENAME , 

2 FN_SIZE) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
TYPE *, ‘Output file: ', FILENAME (1:FN_SIZE) 
REPORT = SS$ NORMAL 

END 


4.3 CLI Routines 


This section describes the individual CLI routines. 
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CLI$SDCL_PARSE—Parse DCL Command String 


Format 


Returns 


Arguments 


The CLI$DCL_PARSE routine supplies a command string to DCL for parsing. 
DCL separates the command string into its individual elements according to the 
syntax specified in the command table. 


CLI$DCL_PARSE [command_sitring] ,table [,poaram_routine] [,prompt_routine] 
[,prompt_string] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


command_string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor—fixed length 


Character string containing the command to be parsed. The command_string 
argument is the address of a descriptor specifying the command string to be 
parsed. If the command string includes a comment (delimited by an exclamation 
mark), DCL ignores the comment. 


If the command string contains a hyphen to indicate that the string is being 
continued, DCL uses the routine specified in the prompt_routine argument to 
obtain the rest of the string. The command string is limited to 256 characters. 
However, if the string is continued with a hyphen, CLI$DCL_PARSE can prompt 
for additional input until the total number of characters is 1024. 


If you specify the command_string argument as zero and specify a prompt 
routine, then DCL prompts for the entire command string. However, if you 
specify the command_string argument as zero and also specify the prompt_ 
routine argument as zero, DCL restores the parse state of the command string 
that originally invoked the image. 


CLI$DCL_PARSE does not perform DCL-style symbol substitution on the 
command string. 


table 

OpenVMS usage: address 
type: address 
access: read only 
mechanism: by value 
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Address of the compiled command tables to be used for command parsing. The 
command tables are compiled separately by the Command Definition Utility 
using the DCL command SET COMMAND/OB] ECT and are then linked with 
your program. A global symbol is defined by the Command Definition Utility that 
provides the address of the tables. The global symbol’s name is taken from the 
module name given on the MODULE statement in the command definition file, or 
from the file name if no MODULE statement is present. 


param_routine 
OpenVMS usage: procedure 


type: procedure value 
access: read only 
mechanism: by reference 


Name of a routine to obtain a required parameter not supplied in the command 
text. The param_routine argument is the address of a routine containing a 
required parameter that was not specified in the command_string argument. 


To specify the parameter routine, use the address of LIB$GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the HP 
OpenVMS RTL Library (LIB$) Manual for information about the calling format. 


If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates the error 
status outward or signals RMS$ EOF in the cases listed in the Description 
section. 


You can obtain the prompt string for a required parameter from the command 
table specified in the table argument. 


prompt_routine 
OpenVMS usage: procedure 


type: procedure value 
access: read only 
mechanism: by reference 


Name of a routine to obtain all or part of the text of a command. The prompt_ 
routine argument is the address of a routine to obtain the text or the remaining 
text of the command depending on the command_string argument. If you 
specify a zero in the command_string argument, DCL uses this routine to 
obtain an entire command line. DCL uses this routine to obtain a continued 
command line if the command string (obtained from the command_string 
argument) contains a hyphen to indicate that the string is being continued. 


To specify the prompt routine, use the address of LIB$GET_INPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the HP 
OpenVMS RTL Library (LIB$) Manual for information about the calling format. 


If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates the error 
status outward or signals RMS$ EOF in the cases listed in the Description 
section. 


prompt_string 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 
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Character string containing a prompt. The prompt_string argument is the 
address of a string descriptor pointing to the prompt string to be passed as the 
second argument to the prompt_routine argument. 


If DCL is using the prompt routine to obtain a continuation line, DCL inserts 
an underscore character before the first character of the prompt string to create 
the continuation prompt. If DCL is using the prompt routine to obtain an entire 
command line (that is, a zero was specified as the command_string argument), 
DCL uses the prompt string exactly as specified. 


The prompt string is limited to 32 characters. The string COMMAND> is the 
default prompt string. 


Description 


The CLI$DCL_PARSE routine supplies a command string to DCL for parsing. 
DCL parses the command string according to the syntax in the command table 
specified in the table argument. 


The CLI$DCL_PARSE routine can prompt for required parameters if you specify 
a parameter routine in the routine call. In addition, the CLI$DCL_PARSE 
routine can prompt for entire or continued command lines if you supply the 
address of a prompt routine. 


If you do not specify a command string to parse and the user enters a null 
string in response to the DCL prompt for a command string, CLI$DCL_PARSE 
immediately terminates and returns the status CLI$ NOCOMD. 


If DCL prompts for a required parameter and the user presses Ctrl/Z, CLI$DCL_ 
PARSE immediately terminates and returns the status CLI$ NOCOMD, 
regardless of whether you specify or do not specify a command string to parse. If 
DCL prompts for a parameter that is not required and the user presses Ctrl/Z, 
CLI$DCL_PARSE returns the status CLI$ NORMAL. 


Whenever CLI$DCL_PARSE encounters an error, it both signals and returns the 
error. 


Condition Values Returned 


CLI$ INVREQTYP Calling process did not have a CLI to perform 
this function, or the CLI did not support the 
request. 

CLI$ IVKEYW Invalid keyword. 

CLI$ IVQUAL Unrecognized qualifier. 

CLI$ IVVERB Invalid or missing verb. 

CLI$ NOCOMD Routine terminated. You entered a null string in 


response to a prompt from the prompt_routine 
argument, causing the CLI$DCL_PARSE routine 
to terminate. 


CLI$¢ NORMAL Normal successful completion. 
CLI$ ONEVAL List of values not allowed; enter one only. 
RMS$ EOF Routine terminated. You pressed Ctrl/Z in 


response to a prompt, causing the CLI$DCL_ 
PARSE routine to terminate. 
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CLI$DISPATCH—Dispatch to Action Routine 


Format 


Returns 


Argument 


Description 


The CLI$DISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLI$DCL_PARSE routine call. 


CLI$DISPATCH _ [userarg] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Values 
Returned. 


userarg 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by value 


Data to be passed to the action routine. The userarg argument is a longword 
that contains the data to be passed to the action routine. This data can be used 
in any way you want. 


The CLI$DISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLI$DCL_PARSE routine call. If the routine is 
successfully invoked, the return status is the status returned by the action 
routine. Otherwise, a status of CLI$_INVROUT is returned. 


Condition Values Returned 


CLI$¢ INVREQTYP Calling process did not have a CLI to perform 
this function or the CLI did not support the 
request. 

CLI¢ INVROUT CLI$DISPATCH unable to invoke the routine. 


An invalid routine is specified in the command 
table, or no routine is specified. 
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CLISGET_VALUE—Get Value of Entity in Command String 


The CLI$GET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command string. 


Format 
CLI$GET_VALUE  entity_desc ,retdesc [,retlength] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
entity_desc 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Character string containing the label (or name if no label is defined) of the entity. 
The entity_desc argument is the address of a string descriptor that points to an 
entity that may appear on a command line. The entity_desc argument can be 
expressed as one of the following: 


¢ A parameter, qualifier, keyword name, or label 
e A keyword path 


The entity_desc argument can contain qualifiers, parameters, keyword names, 
or labels that were assigned with the LABEL clause in the command definition 
file. If you used the LABEL clause to assign a label to an entity, you must specify 
the label in the entity_desc argument. Otherwise, use the name of the entity. 


Use a keyword path to reference keywords used as values of parameters, 
qualifiers, or other keywords. A keyword path contains a list of entity names 

or labels separated by periods. If the LABEL clause was used to assign a label to 
an entity, you must specify the label in the keyword path. Otherwise, you must 
use the name of the entity. 


The following command string illustrates a situation where keyword paths 

are needed to uniquely identify keywords. In this command string, you can 

use the same keywords with more than one qualifier. (This is defined in the 
command definition file by having two qualifiers refer to the same DEFINE TYPE 
statement.) 


$ NEWCOMMAND/QUAL1= (START=5 , END=10) /QUAL2= (START=2 , END=5) 
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The keyword path QUALI1.START identifies the START keyword when it is 
used with QUAL1; the keyword path QUAL2.START identifies the keyword 
START when it is used with QUAL2. Because the name START is an ambiguous 
reference if used alone, the keywords QUAL1 and QUAL2 are needed to resolve 
the ambiguity. 


You can omit keywords from the beginning of a keyword path if they are not 
needed to unambiguously resolve a keyword reference. A keyword path can be no 
more than eight names long. 


If you use an ambiguous keyword reference, DCL resolves the reference by 
checking, in the following order: 


1. The parameters in your command definition file, in the order they are listed 
2. The qualifiers in your command definition file, in the order they are listed 

3. The keyword paths for each parameter, in the order the parameters are listed 
4. The keyword paths for each qualifier, in the order the qualifiers are listed 


DCL uses the first occurrence of the entity as the keyword path. Note that DCL 
does not issue an error message if you provide an ambiguous keyword. However, 
because the keyword search order may change in future releases of OpenVMS, 
you should never use ambiguous keyword references. 


If the entity_desc argument does not exist in the command table, CLI$GET_ 
VALUE signals a syntax error (by means of the signaling mechanism described in 
the HP OpenVMS Programming Concepts Manual). 


retdesc 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Character string containing the value retrieved by CLI$GET_ VALUE. The 
retdesc argument is the address of a string descriptor pointing to the buffer to 
receive the string value retrieved by CLI$GET_VALUE. The string is returned 
using the STR$COPY_DX Run-Time Library routine. 


If there are errors in the specification of the return descriptor or in copying the 
results using that descriptor, the STR$COPY_DX routine will signal the errors. 
For a list of these errors, see the OpfVMS RTL String Manipulation (STR$) 


Manual. 

retlength 

OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Word containing the number of characters DCL returns to retdesc. The 
retlength argument is the address of the word containing the length of the 
retrieved value. 
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The CLI$GET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command string. 


Note 


Only use the CLI$GET_VALUE routine to retrieve values from parsed 
command strings (through DCL or CLI$DCL_PARSE). When you use 

a foreign command to activate an image, the DCL parsing process is 
interrupted. As a result, CLI$GET_ VALUE returns either values from 
the previously parsed command string or a status of CLI$ ABSENT if it 
is the first command string parsed. 


You can use the following label names with CLI$GET_VALUE to retrieve special 


strings: 
$VERB 


$LINE 


Describes the verb in the command string (the first four letters of the 
spelling as defined in the command table, instead of the string that 
was actually typed). 


Describes the entire command string as stored internally by DCL. 
In the internal representation of the command string, multiple 
spaces and tabs are removed, alphabetic characters are converted 
to uppercase, and comments are stripped. Integers are converted 

to decimal. If dates and times are specified in the command string, 
DCL fills in any defaulted fields. Also, if date-time strings (such as 
YESTERDAY) are used, DCL substitutes the corresponding absolute 
time value. 


To obtain the values for a list of entities, call CLI$GET VALUE repeatedly until 
all values have been returned. After each CLI$GET_VALUE call, the returned 
condition value indicates whether there are more values to be obtained. Call 
CLI$GET_VALUE until you receive a condition value of CLI$ ABSENT. 


When you are using CLI$GET VALUE to obtain a list of qualifier or keyword 
values, get all values in the list before starting to parse the next entity. 


Condition Values Returned 


SS$ NORMAL Returned value terminated by a blank or an 


end-of-line. This shows that the value is the last, 
or only, value in the list. 


CLI$_ ABSENT No value returned. The value is not present, or 


the last value in the list was already returned. 


CLI$¢ COMMA Returned value terminated by a comma. This 


shows there are additional values in the list. 


CLI$_CONCAT Returned value concatenated to the next value 


with a plus sign. This shows there are additional 
values in the list. 


CLI$ INVREQTYP Calling process did not have a CLI to perform 


this function or the CLI did not support the 
request. 
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CLISPRESENT—Determine Presence of Entity in Command String 


Format 


Returns 


Argument 


The CLI$PRESENT routine examines the parsed command string to determine 
whether the entity referred to by the entity_desc argument is present. 


CLI$PRESENT _ entity_desc 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Conditon Values 
Returned. 


entity_desc 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Character string containing the label (or name if no label is defined) of the entity. 
The entity_desc argument is the address of a string descriptor that points to an 
entity that may appear on a command line. An entity can be expressed as one of 
the following: 


e A parameter, qualifier, or keyword name or label 
e A keyword path 


A keyword path is used to reference keywords that are accepted by parameters, 
qualifiers, or other keywords. A keyword path contains a list of entity names 
separated by periods. See the description of the entity_desc argument in the 
CLI$GET_ VALUE routine for more information about specifying keyword paths 
as arguments for CLI routines. 


The entity_desc argument can contain parameter, qualifier, or keyword names, 
or can contain labels that were assigned with the LABEL clause in the command 
definition file. If the LABEL clause was used to assign a label to a qualifier, 
parameter, or keyword, you must specify the label in the entity_desc argument. 
Otherwise, you must use the actual name of the qualifier, parameter, or keyword. 


If the entity_desc argument does not exist in the command table, 
CLI$PRESENT signals a syntax error (by means of the signaling mechanism 
described in the HP OpenVMS Programming Concepts Manual). 
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The CLI$PRESENT routine examines the parsed command string to determine 
whether the entity referred to by the entity_desc argument is present. 


When CLI$PRESENT tests whether a qualifier is present, the condition value 
indicates whether the qualifier is used globally or locally. You can use a global 
qualifier anywhere in the command line; you use a local qualifier only after 

a parameter. A global qualifier is defined in the command definition file with 
PLACEMENT=GLOBAL; a local qualifier is defined with PLACEMENT=LOCAL. 


When you test for the presence of a global qualifier, CLISPRESENT determines 
if the qualifier is present anywhere in the command string. If the qualifier 

is present in its positive form, CLISPRESENT returns CLI$ PRESENT; if 

the qualifier is present in its negative form, CLI$PRESENT returns CLI$_ 
NEGATED. 


You can test for the presence of a local qualifier when you are parsing parameters 
that can be followed by qualifiers. After you call CLI$GET_ VALUE to fetch the 
parameter value, call CLI$PRESENT to determine whether the local qualifier 

is present. If the local qualifier is present in its positive form, CLI$PRESENT 
returns CLI$ LOCPRES; if the local qualifier is present in its negative form, 
CLI$PRESENT returns CLI$ LOCNEG. 


A positional qualifier affects the entire command line if it appears after the verb 
but before the first parameter. A positional qualifier affects a single parameter 
if it appears after a parameter. A positional qualifier is defined in the command 
definition file with the PLCACEMENT=POSITIONAL clause. 


To determine whether a positional qualifier is used globally, call CLI$SPRESENT 
to test for the qualifier before you call CLI$GET VALUE to fetch any parameter 
values. If the positional qualifier is used globally, CLIS$PRESENT returns either 
CLI$ PRESENT or CLI$ NEGATED. 


To determine whether a positional qualifier is used locally, call CLISPRESENT 
immediately after a parameter value has been fetched by CLI$GET_ VALUE. The 
most recent CLI$GET_VALUE call to fetch a parameter defines the context for a 
qualifier search. Therefore, CLISPRESENT tests whether a positional qualifier 
was specified after the parameter that was fetched by the most recent CLI$GET_ 
VALUE call. If the positional qualifier is used locally, CLISPRESENT returns 
either CLI$ LOCPRES or CLI$¢ LOCNEG. 


Condition Values Returned 


CLI$ ABSENT Specified entity not present, and it is not present 
by default. 

CLI$ DEFAULTED Specified entity not present, but it is present by 
default. 

CLI$ INVREQTYP Calling process did not have a CLI to perform 
this function, or the CLI did not support the 
request. 

CLI$ LOCNEG Specified qualifier present in negated form (with 


/NO) and used as a local qualifier. 
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CLI$_LOCPRES 
CLI$ NEGATED 


CLI$_ PRESENT 


Specified qualifier present and used as a local 
qualifier. 

Specified qualifier present in negated form (with 
/NO) and used as a global qualifier. 

Specified entity present in the command string. 
This status is returned for all entities except 
local qualifiers and positional qualifiers that are 
used locally. 


CLI-14 Command Language Interface (CLI) Routines 


*) 


Common File Qualifier Routines 


This chapter describes the common file qualifier (UTIL$CQUAL) routines. The 
UTIL$CQUAL routines allow you to parse the command line for qualifiers 
related to certain file attributes, and to match files you are processing against the 
selected criteria retrieved from the command line. 


5.1 Introduction to the Common File Qualifier Routines 


The common file qualifier routines begin with the characters UTIL$CQUAL. 
Your program calls these routines using the OpenVMS Calling Standard. When 
you call a UTIL$CQUAL routine, you must provide all the required arguments. 
Upon completion, the routine returns its completion status as a condition value. 
Section 5.3 provides detailed descriptions of the routines. 


The following table lists the common file qualifier routines. 


Table 5-1 UTIL$CQUAL Routines 
Routine Name Description 


UTIL$CQUAL_FILE_PARSE Parses the command line for the file qualifiers 
listed in Table 5-2, and obtains associated values. 
Returns a context value that is used when calling 
the matching and ending routines. 


UTIL$¢CQUAL_FILE_MATCH Compares the routine file input to the command line 
data obtained from the parse routine call. 
UTIL$CQUAL_FILE_END Deletes all virtual memory allocated during the 


command line parse routine call. 


UTIL$¢CQUAL_CONFIRM_ACT Prompts a user for a response from 
SYS$COMMAND. 


5.2 Using the Common File Qualifier Routines 
Follow these steps to use the common file qualifier routines: 


1. Call UTIL$CQUAL_FILE_PARSE to parse the command line for the common 
file qualifiers. (See Table 5-2 for a list of the qualifiers.) 


2. Call UTIL$CQUAL_FILE_MATCH for each checked file UTIL$CQUAL_ 
FILE_MATCH returns an indication that the file is, or is not, to be processed. 


3. Call UTIL$CQUAL_FILE_END to release the virtual memory held by the 
common file qualifier package. 


You may optionally call UTIL$CQUAL_CONFIRM_ACT to ask for user 
confirmation without calling the other common qualifier routines. 
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5.2.1 Calling UTILGCQUAL_FILE_PARSE 


When you call UTIL$CQUAL_ FILE PARSE, specify the qualifiers listed in 
Table 5-2 that you want to parse by setting bits in a flags longword and passing 
the longword address as the first parameter. 


Table 5-2 UTIL$CQUAL_FILE_PARSE Command Line Qualifiers 


Qualifier Description 

BEFORE= Selects a file before the specified time. 

CONFIRM Prompts the user for confirmation. 

SINCE= Selects a file on or after the specified time. 
MODIFIED Specifies that the file’s revision time (time of last 


modification) is used for comparison with the time 
specified in either the /BEFORE or /SINCE qualifier. 


CREATED (default) Specifies that the file's creation time is used for 
comparison with the time specified in either the 
/BEFORE or /SINCE qualifier. 


BACKUP Specifies that the file’s most recent backup time is used 
for comparison with the time specified in either the 
/BEFORE or /SINCE qualifier. 


EXPIRED Specifies that the file’s expiration date is used for 
comparison with the time specified in either the 
/BEFORE or /SINCE qualifier. 


BY_OWNER= Selects a file based on the file owner’s user identification 
code. The default is the UIC of the current process. 
EXCLUDE= Selects a file only if it does not match the specification 


or list of specifications given with this qualifier. 


The following segment from a sample C program shows the flags longword set to 
search for the common file qualifiers supported by this package: 


input_flags = UTIL$M_CQF_CONFIRM | UTIL$M_CQF EXCLUDE | 
UTILS$M_CQF BEFORE | UTILSM COF SINCE | 
UTILS$M_CQF CREATED | UTILSM_COQF MODIFIED 
UTILS$M_CQF EXPIRED | UTILSM_COF BACKUP 
UTILS$M_CQF BYOWNER; 


Optionally, you can provide the flags longword address for UTIL$CQUAL_FILE_ 
PARSE to return an indication of what common file qualifiers were present on 
the command line. For example, if ‘CONFIRM is enabled and was found on the 
command line, the application can determine if confirmation prompts need to be 
built. The following is an example call in C: 


status = UTILSCQUAL FILE PARSE (&input flags, 
&context, 
&output flags) ; 


The context variable contains the address of the common file qualifier value 
which is used in other common file qualifier routine calls. 
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5.2.1.1 Specifying Times 
The times specified with the /SINCE= and /BEFORE = qualifiers must be in 
either absolute or combination time format. When DCL gathers these times from 
the command line, it converts truncated time values, combination time values, 
and keywords (such as BOOT, LOGIN, TODAY, TOMORROW, or YESTERDAY) 
into absolute time format. Files are selected based on the times entered on 
the command line, and are compared to the time of the file’s backup date, 
creation date (default), expiration date, or last modification date as indicated 
by the modifier qualifiers (BACKUP, /CREATED, /EXPIRED, and /MODIFIED 
respectively. 


For complete information on specifying time values, see the OpenVMS User’s 
Manual or the topic DCL_TIPS Date_Time in online help. 


5.2.1.2 Specifying Exclude Pattern Strings 
Pattern strings are used to exclude specific files from being processed. The 
pattern strings may contain a combination of a directory specification, filename, 
filetype, and version number. Node names and device names are not permitted. 
Relative directory specifications are allowed (such as [.subdirectory] or [-]), 
but relative version numbers have no meaning as a pattern string component. 
UTIL$¢CQUAL_FILE_PARSE assumes relative version numbers are a wildcard, 
and matches all versions. An FID or DID specification is also not allowed. 


To exclude more than one specification, use a comma-separated list enclosed 
within parentheses. 


5.2.2 Calling UTILS6CQUAL_FILE_MATCH 


When calling UTIL$CQUAL_FILE_MATCH, specify a file that you want checked 
against criteria in the common file qualifier context. The context address was 
returned as the first parameter in a prior call to UTIL$CQUAL_FILE_PARSE, 
and is the first parameter for UTIL$CQUAL_FILE_MATCH. 


To specify a file, provide either a string descriptor containing the specification or 
an RMS FAB. The FAB must contain an NAM block that has been filled in by 
RMS, so that comparisons with excluded file specifications can occur. If the FAB 
indicates that the file is open, and any of the /BEFORE, /SINCE or /BY_ OWNER 
qualifiers are to be evaluated, then the appropriate XAB blocks must be in the 
XAB chain (XABDAT and XABPRO). The XAB blocks must be filled in by RMS 
during the file open. 


Note 


The files passed in with a DID or an FID specification may cause the 
common qualifier package to stop processing if that portion of the file 
specification needs to be matched against a pattern string from the 
/EXCLUDE qualifier. 
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5.2.2.1 Specifying Prompts 
You can provide one or two prompts when specifying prompts as confirmation 
messages. If confirmation is active, at least one prompt string must be 
specified. When providing two prompts, use the shorter prompt as the prompt_ 
string _1 parameter. Table 5-5 lists the valid confirmation prompt responses. 
CONDENSED and EXPANDED are used when switching between prompts. 


The user responding CONDENSED (or just C) displays the prompt_string 1 
string. For a more descriptive or detailed prompt, use prompt_string_2 in your 
call. For example, the OpenVMS utilities construct prompts from the short and 
long fields of an RMS NAML block. The prompt from the short field is passed 
through prompt_string_1, and the prompt from the long field is passed through 
prompt_string 2. 


You have the option of specifying a prompt routine. The first parameter for the 
prompt routine will contain a string descriptor of the prompt to be displayed. 
The second parameter will contain the address of a buffer for the user’s response. 
You must modify the response buffer to reflect the length of the user’s response. 
Table 5-5 lists the valid prompt routine responses. All other responses display an 
invalid response warning, and call the prompt routine again. 


When two prompts are supplied to UTIL$CQUAL_FILE_ MATCH, the optional 
parameter current_form can be used to determine which prompt string is 
displayed first. Table 5-4 lists the valid current_form values. 


If the value stored in current_form is not in the values listed, then UTIL $K_ 
CQF_SHORT is assumed. If the value is UTIL$K_CQF_UNSPECIFIED, or 

this parameter is absent from the call, then the form stored in the common file 
qualifier database is used. The value currently stored in the common file qualifier 
database is the final form active when UTIL$CQUAL_FILE_MATCH returned 
from the previous call with the current database context. If there was no previous 
call, UTIL$K_CQF_SHORT is stored in the database. 


If the current_form parameter can be written to, the final active form is stored 
before UTIL$¢CQUAL_FILE_MATCH returns. 


Note 


If only one prompt string is provided to UTIL$¢CQUAL_FILE_ MATCH, 
the final form will be the form corresponding to that prompt string even 
if the user requests the alternate form. For example, if only the short 
prompt string is provided and the user requests the long prompt, the user 
receives the short prompt. UTIL$K_CQF SHORT is returned through the 
current_form parameter if that parameter is writable. 


5.2.2.2 Ignoring Qualifiers 
The final parameter, which is also optional, is a flags longword used to ignore 
certain qualifier processing when calling UTIL$CQUAL_FILE MATCH. The 
modifier qualifiers for date comparisons (CREATED, /MODIFIED, /BACKUP, 
and /EXPIRED) cannot be ignored. If either the /SINCE or /BEFORE modifier 
qualifiers are active, then the date comparison modifier qualifiers must be active 
to determine which dates to compare. For example, to operate on the top two 
versions of a file set when confirmation is active, an application can keep track 
of the first two instances and prompt the user. Once the application reaches that 
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number, it sets the UTIL$M_CQF_CONFIRM bit in the disable parameter flags 
longword, and the user is not prompted for confirmation during that call. The 
following is an example call in C: 


status = UTILSCQUAL FILE MATCH (&context, 
0, 
&result_desc, 
&short_prompt, 
&long prompt, 


&prompt_form, 
&ignore flags) ; 


5.2.3 Calling UTIL$CQUAL_FILE_END 


When calling UTIL$¢CQUAL_FILE_END, specify the context variable that 
contains the common file qualifier database context to be terminated. The 
database location was returned in a prior call to UTIL$CQUAL_FILE_PARSE. 
The UTIL$CQUAL_FILE_END call deallocates all virtual memory held by the 
common file qualifier value in the context parameter. The context variable is 
zeroed before this routine returns. The following is an example call in C: 


status = UTILSCQUAL FILE END (&context) ; 


5.2.4 Calling UTILGCQUAL_CONFIRM_ACT 


Similar to UTIL$CQUAL_FILE MATCH, the parameter list used when calling 
UTIL$CQUAL_CONFIRM_ACT is a subset of the UTIL$¢CQUAL_ FILE MATCH 
parameter list. 


When specifying prompts as confirmation messages, you can provide one or two 
prompts. At least one prompt string must be specified. When providing two 
prompts, use the shorter of the two prompts as the prompt_string_1 parameter. 
Table 5-5 lists valid responses to a confirmation prompt, and lists CONDENSED 
and EXPANDED to switch between prompts. 


The user responding CONDENSED (or just C) causes the prompt_string 1 
string to be displayed. To give the user a more descriptive or detailed prompt, 
use prompt_string_2 in your call. For example, the OpenVMS utilities construct 
prompts from the short and long fields of an RMS NAML block. The prompt from 
the short field is passed through prompt_string_1, and the prompt from the long 
field is passed through prompt_string_2. 


You have the option of specifying a prompt routine. The first parameter for the 
prompt routine is a string descriptor of the prompt to be displayed. The second 
parameter contains the address of a buffer for the user’s response. You must 
modify the response buffer to reflect the length of the user's response. Table 5-5 
lists valid prompt routine responses. All other responses display an invalid 
response warning, and call the prompt routine again. 


When two prompts are supplied to UTIL$CQUAL_CONFIRM_ACT, the optional 
parameter current_form can be used to determine which prompt string is 
displayed first. The valid values are listed in Table 5-4. If the value stored is 
other than the values listed, UTIL$K_CQF_SHORT is assumed. If the value is 
UTIL$K_CQF_UNSPECIFIED or this parameter is absent from the call, then 
UTIL$K_CQF_SHORT is used. 
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If the current_form parameter can be written to, the final active form is stored 
before UTIL$¢CQUAL_CONFIRM_ACT returns. 


Note 


If only one prompt string is passed into the UTIL$CQUAL_CONFIRM_ 
ACT call, the final form will be the form corresponding to that prompt 
string even if the user requests the alternate form. For example, if 

only the short prompt string is provided and the user requests the long 
prompt, the user receives the short prompt again. UTIL$K_CQF_ SHORT 
is returned through the current_form parameter if that parameter is 
writable. 


The following is an example call in C: 


status = UTILSCQUAL CONFIRM ACT (&short_prompt, 
&long prompt, 


&prompt_ form) ; 


5.2.5 Creating a Command Language Definition File 


For UTIL$¢CQUAL_FILE PARSE to function properly, you need the following 
Command Language Definition (CLD) file template in the command tables being 
examined: 


define verb foo 
image foo 
parameter pl,prompt="File", value (list, impcat, required, type=$infile) 
qualifier confirm 
qualifier exclude, value (required, list) 
qualifier before, value (default=today, type=Sdatetime) 
qualifier since, value (default=today, type=Sdatetime) 


qualifier created 
qualifier modified 
qualifier expired 
qualifier backup 


qualifier by owner, value (type=$uic) 


For example, if the line qualifier expired was omitted, a call to UTIL$CQUAL _ 
FILE PARSE would result in: 


$ foo *.c 
SCLI-F-SYNTAX, error parsing ‘EXPIRED’ 
-CLI-E-ENTNF, specified entity not found in command tables 
¢TRACE-F-TRACEBACK, symbolic stack dump follows 
image module routine line rel PC abs 


Note 


A default value for the /SINCE=and /BEF ORE = qualifiers is provided in 
the CLD file. If you do not require a value, specify a default or you may 
not get the desired result. 
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The following example shows a C program that retrieves files from the command 
line, and lists which ones will be processed, if processing is required. 


Example 5-1 Using UTIL$CQUAL Routines to Process Files 


$ create foo.c 
#include <stdio.h> 
include <string.h> 


include <rms.h> 

include <starlet.h> 
#include <descrip.h> 
#include <lib$Sroutines.h> 
include <libfildef.h> 
include <cli$routines.h> 


include <cqualdef.h> 
include <utilSroutines.h> 


ifdef NAMLSC_BID /* determine if HFS support is here */ 
define HFS Support 1 

#else 

#define HFS Support 0 

endif 


#if !HFS Support /* compensate for lack of HFS support */ 
define naml$l1_rsa nam$l_rsa 

define naml$b rsl nam$b rsl 

#define naml$l_ long result nam$l rsa 

#define naml$l_ long result _size nam$b rsl 

define NAMLSC_MAXRSS NAMSC_MAXRSS 

define LIBSM FIL LONG NAMES 0 

#endif 


unsigned int input flags; 
unsigned int output_flags; 
unsigned int ignore flags = 0; 
unsigned int *context; 

char get_value [NAMSC_MAXRSS] ; 


char *prompt_string = "Confirmation for "; 
char *prompt_end = " [N] ? "; 

char *process = " Will process "; 

char *noprocess = " Will not process "; 


char short_string[NAM$C_MAXRSS+80] ; 
unsigned int prompt_form = 0; 

unsigned int status; 

struct fabdef *find file context; 
unsigned int find_ file flags; 
unsigned short ret _length; 
SDESCRIPTOR(parm_1, "P1"); 
SDESCRIPTOR (get_val desc, get value) ; 
SDESCRIPTOR (short prompt, short “string) ; 
SDESCRIPTOR (result _desc, ""); 

char long string [NAMLSC_| MAXRSS+80] ; 
char outstring[NAMLSC_ MAXRSS+80] ; 
SDESCRIPTOR (long prompt, long_ string) ; 
# 
s 
# 
st 
# 


if HFS Support 
truct namldef *nam_block; 


(continued on next page) 
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Example 5-1 (Cont.) Using UTIL$CQUAL Routines to Process Files 


extern UTILS QUICONACT; 
extern UTILS QUIPRO; 


int main(void) { 


input_flags = 


UTILSM_COQF CONFIRM 
UTILSM_CQF BEFORE 

UTILSM_CQF_ CREATED 
UTILSM_CQF EXPIRED 
UTILSM_CQF BYOWNER; 


/* external literal */ 
/* external literal */ 


UTIL$M_CQF EXCLUDE | 
UTILSM_CQF SINCE | 
UTILSM_CQF MODIFIED 
UTILSM_CQF BACKUP 


if (!(status = UTILSCQUAL FILE PARSE ( é&input_flags, 


return status; 


I 


find file flags 


get_val_desc.dsc$w_] 
status = cli$get_val 


result_desc.dsc$b cl 


= LIBSM FIL MULTIPLE 


result _desc.dsc$a pointer = 0; 


while (status & 


get_val_desc.dsc$w_length = ret_] 


1) 


&context , 
&output_ flags) & 1)) { 


| LIBSM_FIL LONG NAMES; 


length = sizeof (get value) ; 
lue(&parm_1, &get_val_ desc, &ret_length) ; 


lass = DSC$K_CLASS D; 


length; 


while ((status != (int) &UTIL$ QUIPRO) && /* treat as external literal*/ 


(LIBSFIND FILE(&get_val_desc, &result_desc, 
&find file context, 0, 0, 0, 


#if HFS Support 


&find file flags 


nam_block = find file contex 


#else 


nam block = find file contex 


#endif 


if ((output_flags && UTILSM_ 
strcpy(short_ string, prompt string) ; 


strncat (sh 


strcat (short string, prompt_end) ; 
pt.dsc$w_length = strlen(short string) ; 

g string, prompt string) ; 

tring, nam_block->naml$1_long_result, 


short_prom 
strepy (lon 
strncat (long _s 


strcat (long_string, prom 


(int)nam_blo 


(int)nam_blo 


& 1)) { 


t->fabS1 naml; 


t->fab$1_ nam; 


COQF CONFIRM) != 0) { 


ort_string, nam_block->naml$l_rsa, 


ck->naml$b_rs1) ; 


ck->naml$1_ long result_size) ; 
jpt_end) ; 


long prompt.dscSw_length = strlen(long_string) ; 


else { 


short_prompt.dsc$w_lengt 
long prompt.dscSw_length 


h 0; 


0; 


if ((status = UTILSCQUAL FILE MATCH(&context, 


0, 

&result_desc, 
&short_prompt, 

&long prompt, 

0, 

&prompt_ form, 

&ignore flags)) & 1) { 


strcpy(outstring, process) ; 
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Example 5-1 (Cont.) Using UTIL$CQUAL Routines to Process Files 


else { 
strcpy(outstring, noprocess) ; 
if (prompt_form == UTIL$K_CQF SHORT) { 
strncat (outstring, nam _block->naml$l_rsa, 
(int)nam_block->naml$b_rs1l) ; 


else { 
strncat (outstring, nam _block->naml$l1_long result, 
(int)nam_block->naml$l_ long result_size) ; 


hi 
printf ("%s\n", outstring) ; 
if (status == (int) &UTIL$ QUICONACT) { /* treat as external literal*/ 
output_flags &= ~UTILSM_CQF_CONFIRM; 
if (status != (int) &UTIL$ QUIPRO) { 
get_val_desc.dsc$w_length = sizeof (get value) ; 
status = cli$get_value(&parm_1, &get_val_desc, &ret_length) ; 
bi 
status = UTILSCQUAL FILE END (&context) ; 
return status; 


} 

$ ec/list foo.c 

$ link foo.c 

$ set command foo.cld 

$ define foo sys$disk: [] foo.exe 

$ directory/noexclude 

Directory MDA2000: [main] 

EDTINI.EDT;1 FOO.BAR;1 FOO.C;2 
FOO.C;1 FOO.CLD;2 FOO.CLD;1 
FOO. EXE; 3 FOO. EXE; 2 FOO. EXE;1 
FOO.LIS;1 FOO.OBJ;1 LAST .COM;1 
LOGIN.COM;1 MAIL.MAT;1 MDAO.DAT;1 
NOTE. DAT; 1 QUEUE .COM;1 TPUINI.TPU;1 


(continued on next page) 
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Example 5-1 (Cont.) Using UTIL$CQUAL Routines to Process Files 


Total of 18 files. 
$ foo/exclude=*.c *.*;* 


Will process MDA2000: [main] EDTINI.EDT;1 
Will process MDA2000: [main] FOO.BAR;1 
Will not process MDA2000: [main] FOO.C;2 
Will not process MDA2000: [main] FOO.C;1 
Will process MDA2000: [main] FOO.CLD;2 
Will process MDA2000: [main] FOO.CLD;1 
Will process MDA2000: [main] FOO.EXE;3 
Will process MDA2000: [main] FOO.EXE;2 
Will process MDA2000: [main] FOO.EXE;1 
Will process MDA2000: [main] FOO.LIS;1 
Will process MDA2000: [main] FOO.OBJ;1 
Will process MDA2000: [main] LAST.COM;1 
Will process MDA2000: [main] LOGIN.COM;1 
Will process MDA2000: [main]MAIL.MAI;1 
Will process MDA2000: [main]MDAO.DAT;1 
Will process MDA2000: [main] NOTE.DAT;1 
Will process MDA2000: [main] QUEUE.COM;1 
Will process MDA2000: [main] subdir.DIR;1 
Will process MDA2000: [main] TPUINI.TPU;1 

$ foo/confirm *.* 

Confirmation for MDA2000:[main]EDTINI.EDT;1 [N] ? n 
Will not process MDA2000: [main] EDTINI.EDT;1 


Confirmation for MDA2000: [main] FOO.BAR;1 [N] ? n 
Will not process MDA2000: [main] FOO.BAR;1 
Confirmation for MDA2000:[main]FOO.C;2 [N] ? y 
Will process MDA2000: [main] FOO.C;2 
Confirmation for MDA2000:[main]FOO.CLD;2 [N] ? g 
Will not process MDA2000: [main] FOO.CLD;2 
$ foo/since=yesterday/modified/exclude=(*.*;2,1*) foo.*;*,*.com;* 
Will process MDA2000: in] FOO.BAR;1 
Will not process MDA2000: [main] FOO.C;2 
Will process MDA2000: in] FOO.C;1 
Will not process MDA200 ain] FOO.CLD;2 
Will process MDA2000: in] FOO.CLD;1 


Will process MDA2000: in] FOO. EXE; 3 
Will not process MDA200 in] FOO. EXE; 2 
Will process MDA2000: in] FOO. EXE; 1 
Will process MDA2000: in] FOO.LIS;1 
Will process MDA2000: in] FOO.OBJ;1 


Will not process MDA200 
Will not process MDA200 
Will process MDA2000: 


ain] LAST.COM;1 
ain] LOGIN.COM;1 
in] QUEUE.COM;1 


woorvwo pow von om 
m@ 
t= 


5.3 UTIL$CQUAL Routines 
This section describes the UTIL$CQUAL routines. 
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UTIL$CQUAL_ FILE PARSE—Parse the Command Line 


Format 


Returns 


Arguments 


The UTIL$CQUAL_FILE_PARSE routine parses the command line for the 
common file qualifiers. 


UTIL$CQUAL_FILE_PARSE | flags ,context [,found_flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition Values Returned lists condition values that this routine returns. 


flags 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword of bit flags. UTIL$¢CQUAL_FILE_PARSE scans the command line for 
the qualifiers whose associated bit is set in the flags longword. The following 
table lists the allowed mask and field specifier values. 


Table 5-3 UTIL$CQUAL_FILE_PARSE Flags and Masks 


Qualifier Mask Value Field Specifier 

/CONFIRM UTIL$M_CQF_CONFIRM UTIL$V_CQF_CONFIRM 
/EXCLUDE UTIL$M_CQF_EXCLUDE UTIL$V_CQF_ EXCLUDE 
/BEFORE UTIL$M_CQF_BEFORE UTIL$V_CQF_BEFORE 
/SINCE UTIL$M_CQF_SINCE UTIL$V_CQF_SINCE 
/CREATED UTIL$M_CQF_CREATED UTIL$V_CQF_CREATED 
/MODIFIED UTIL$M_CQF_ MODIFIED UTIL$V_CQF_MODIFIED 
/EXPIRED UTIL$M_CQF_EXPIRED UTIL$V_CQF_EXPIRED 
/BACKUP UTIL$M_CQF_BACKUP UTIL$V_CQF_BACKUP 


/BY_OWNER UTIL$M_CQF_BYOWNER _ UTIL$V_CQF_BYOWNER 


context 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


The address of a longword that receives the common file qualifier database 
address. The address of the context variable must be passed to the 
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Description 


UTIL$¢CQUAL_FILE_MATCH and UTIL$CQUAL_FILE_END routines when 
they are called. 


found_flags 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Longword of bit flags. This optional parameter is the longword address of the 
value that indicates which common file qualifiers were present on the command 
line. The mask and field specifier values are the same values as the flags 
parameter, and are listed in Table 5-3. 


Using the CLI¢PRESENT and CLI$GET_VALUE routines, the UTIL$CQUAL_ 
FILE PARSE routine searches the command line for the qualifiers specified 

in the flags longword. When command line parsing finishes, UTIL$¢CQUAL _ 
FILE PARSE returns a pointer to the common file qualifier value in the context 
parameter. 


The context parameter must be used when calling either the UTIL$CQUAL_ 
FILE_MATCH or UTIL$CQUAL_FILE_END routines. If a third parameter is 
specified, UTIL$CQUAL_ FILE PARSE returns a longword of flags indicating 
which qualifiers were found during the command line parse. The mask and field 
specifiers are listed in Table 5-3. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

LIB$ INVARG Invalid argument. A bit in the flags parameter 
was set without an associated qualifier. 

CLI$_INVQUAVAL An unusable value was given on the command 


line for any of the following qualifiers: 
/EXCLUDE, /BEFORE, /SINCE, or /BY_OWNER 
(for example, /BEFORE =mintchip). 

SS$_ CONFQUAL More than one of the following appeared on the 
command line at the same time: /CREATED, 
/MODIFIED, /EXPIRED, /BACKUP. 


Any unsuccessful return from LIB$GET_VM. 
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UTIL$CQUAL_FILE_MATCH—Match a File with Selection Criteria 


Format 


Returns 


Arguments 


The UTIL$CQUAL_ FILE MATCH routine matches a file with the selection 
criteria. 


UTIL$CQUAL_FILE_MATCH context [,user_fab] [,file_name] [,prompt_string_1] 
[,prompt_string_2] [,prompt_rtn] [,current_form] 
[ disable] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition Values Returned lists condition values that this routine returns. 


context 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The longword address that received the common file qualifier database address 
from a prior call to UTIL$CQUAL_FILE_PARSE. 


user_fab 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The FAB address of the file to be evaluated. This FAB must point to a valid NAM 
or NAML block. If the file is open and the file header criteria are to be evaluated, 
the appropriate XABs (XABPRO or XABDAT) must be chained to the FAB and 
properly filled in by RMS. If the file is not open when this routine is called, then 
the XAB chain is not necessary, but may be present. This argument is optional. 
If it is not present, the file_name parameter must be present. Both arguments 
may not be present at the same time. 


file_name 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The file name descriptor address of the file to be processed. This parameter can 
be used instead of the user_fab argument. Both arguments may not be present 
at the same time. 
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prompt_string_1 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword address of a prompt string descriptor. This prompt is used when 
prompting to a terminal device and the current prompt form is UTIL$K_CQF_ 
SHORT. 


prompt_string 2 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by descriptor 


Longword address of a prompt string descriptor. This prompt is used when 
prompting to a terminal device and the current prompt form is UTIL$K_CQF_ 


LONG. 

prompt_rtn 

OpenVMS usage: procedure 

type: longword (unsigned) 
access: function call 
mechanism: by value 


User-supplied longword routine address used for prompting and accepting input 
from the user. The user routine is responsible for end-of-file processing and must 
return RMS$ EOF when appropriate. 


current_form 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read write 
mechanism: by reference 


This optional parameter supplies the initial prompt form displayed to the user. If 
it contains the value UTIL$K_CQF_UNSPECIFIED, then the form last requested 
by the user is used if that form is available. If there was no previous call to 
UTIL$CQUAL_FILE_MATCH, and the current_form is unspecified, UTIL$K_ 
CQF_SHORT is assumed. 


When exiting UTIL$CQUAL_FILE_MATCH, the current_form parameter 
contains the last user requested prompt form. If a previous call to UTIL$CQUAL _ 
FILE MATCH requested quit processing or quit confirmation prompting, then 
this parameter is not modified. 


disable 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword of bit flags. This optional parameter specifies which common file 
qualifiers are ignored in the current call to UTIL$CQUAL_FILE_ MATCH. 
Qualifiers that cannot be ignored are /CREATED, /MODIFIED, /EXPIRED, and 
/BACKUP). 
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Description 


UTIL$¢CQUAL_FILE_MATCH compares the file named in either the user_fab 

or file_name parameter (only one can be specified) against criteria specified by 
the common file qualifier database pointed to by the context and the disable 

parameter flags. UTIL$CQUAL_FILE_MATCH returns a status as to whether 

the file does or does not match the criteria. 


If a failure occurs during processing, such as those listed in the Abnormal 
Completion Codes, the routine quits processing files for the context under 

which the failure occurred. A processing failure is the same as receiving a quit 
processing response from a user prompt. Any additional calls to this routine with 
the context that incurred the processing failure will return UTIL$ QIOPRO. This 
applies even if the user responded ALL to a previous confirmation prompt. 


For a description of the /CONFIRM prompting, see UTIL$CQUAL_CONFIRM_ 
ACT. 


Note 


The UTIL$¢CQUAL_FILE_MATCH current_form parameter is 
different from the same parameter in UTIL$CQUAL_CONFIRM_ACT. 
UTIL$CQUAL_FILE_ MATCH retains the user's last requested form 
between calls. 


Condition Values Returned 


Normal Completion Codes: 


SS$ NORMAL File matches the criteria and can be processed. 


UTIL$ QUICONACT User requests that confirmation prompting cease, 
but that other common file qualifier criteria be 
applied on subsequent file specifications. 


UTIL$ FILFAIMAT File failed the evaluation, and should not be 
processed. 
UTIL$QUIPRO User requests that processing stops. 


Abnormal Completion Codes: 


LIB$INVARG Incorrect parameter list. 

SS$ ACCVIO Unable to access one or more of the parameters 
(such as the common file database or user_fab). 

UTIL$ FILFID File specification contains an FID. Due to file 


specification aliases, converting an FID toa file 
specification is inappropriate for /EXCLUDE 
processing. 

UTIL$ FILDID File specification contains a DID. Due to 
directory specification aliases, converting a 
DID to a directory patch is inappropriate for 
/EXCLUDE processing when the directory patch 
needs to be compared. 
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LIB$ INVXAB Invalid XAB chain. A necessary XAB (XABPRO 
or XABDAT) is missing from the opened file’s 
XAB chain. 


Any unsuccessful code from RMS, LIB$GET_VM, or any unsuccessful return 
status from the user-supplied routine (other than RMS$ EOF). 
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UTIL$CQUAL_FILE_END—End Processing 


Format 


Returns 


Arguments 


Description 


The UTIL$CQUAL_FILE_END routine returns all allocated virtual memory from 
the call to UTIL$CQUAL_FILE PARSE. 


UTIL$¢CQUAL_FILE_END context 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition Values Returned lists condition values that this routine returns. 


context 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read write 
mechanism: by reference 


The longword address that received the common file qualifier database address 
from a prior call to UTIL$CQUAL_FILE_PARSE. 


UTIL$CQUAL_FILE_END deallocates the virtual memory obtained by the 
common file qualifier package during the call to UTIL$CQUAL_FILE_ PARSE. 
The virtual memory held information for calls to UTIL$¢CQUAL_FILE_MATCH. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
Any unsuccessful code from LIB$FREE_VM. 
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UTILS$CQUAL_CONFIRM_ACT—Ask User for Confirmation 


The UTIL$CQUAL_CONFIRM_ACT routine prompts the user for confirmation, 
using the optional prompt routine if present, and returns an indication of the 
user's response. 


Format 
UTIL$CQUAL_CONFIRM_ACT  [prompt_string_1] [,prompt_string_ 2] [,prompt_rtn] 
[,current_form] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition Values Returned lists condition values that this routine returns. 
Arguments 


prompt_string 1 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by descriptor 


Longword address of a prompt string descriptor. The prompt is used when 
prompting to a terminal device, and the current prompt form is UTIL$K_CQF _ 
SHORT. 


prompt_string_2 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by descriptor 


Longword address of a prompt string descriptor. The prompt is used when 
prompting to a terminal device, and the current prompt form is UTIL$K_CQF _ 


LONG. 

prompt_rtn 

OpenVMS usage: procedure 

type: longword (unsigned) 
access: function call 
mechanism: by value 


Longword address of a user-supplied routine for prompting and accepting user 
input. The user routine is responsible for end-of-file processing and must return 
RMS$ EOF when appropriate. 
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current_form 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read write 
mechanism: by reference 


This optional parameter supplies the initial prompt form to be displayed to the 
user. If present, this parameter receives the form of the last prompt displayed. 
The following table shows the valid prompting form values: 


Table 5-4 Prompting Form Values 


Value Description 
UTIL$K_CQF_SHORT Use prompt _string_1. 
UTIL$K_CQF_LONG Use prompt _string_2. 
UTIL$K_CQF_ UNSPECIFIED None specified; use default. 


UTIL$CQUAL_CONFIRM_ACT prompts the user for confirmation. You must 
supply at least one prompt string to this routine. If you supply both strings, you 
should have an expanded and condensed form of the prompt. The condensed form 
should be supplied through the prompt_string_1 parameter; the expanded form 
through prompt_string_2. The prompt string supplied by prompt_string_lis 
initially used if the prompt_string_1 is present, does not have a length of zero, 
and either: 


e The current_form parameter is not specified 

e The current_form parameter is specified and contains: 
— UTIL$K_CQF_SHORT 
— UTIL$K_CQF_UNSPECIFIED 
- A value greater than UTIL$K_CQF_MAX_FORM 


The prompt string supplied by prompt_string 2 is used initially if prompt_ 
string_2 is present, does not have a length of zero, and either: 


¢ prompt_string_1 is not present or has a length of zero 


e The current_form parameter is specified and contains the value UTIL $K _ 
CQF_LONG 


Once the initial form is displayed, the user can switch between the two forms by 
responding to the prompt with either CONDENSED or EXPANDED. The user 
can only switch to another form if there was a prompt string provided for that 
form. Responding with either CONDENSED or EXPANDED causes a reprompt 
to occur, even if the current display form was not switched. 


If a prompt routine is provided, the routine is called with the address of the 
prompt string descriptor in the first parameter, and the string descriptor address 
to receive the user’s response in the second parameter. The routine returns a 
success status or RMS$ EOF. 


Common File Qualifier Routines CQUAL-19 


Common File Qualifier Routines 
UTIL$CQUAL_CONFIRM_ACT 


If an unsuccessful status other than RMS$ EOF is received, then UTIL$CQUAL _ 
CONFIRM_ACT exits without processing any response in the response buffer 
(the second parameter that was passed to the prompt routine). UTIL$CQUAL _ 
CONFIRM_ACT returns the status received from the user prompt routine. The 
prompt routine is responsible for end-of-file processing, and must return RMS$_ 
EOF when appropriate. If an optional prompt routine is provided, it should be 
provided for all calls to UTIL$CQUAL_CONFIRM_ACT. Not doing so can cause 
unpredictable end-of-file processing. 


When the user is prompted, they may respond with the following: 


Table 5-5 Prompt Responses 


Positive Negative Stop Stop Switch 
Response Response Processing Prompting Prompts 
YES NO QUIT ALL CONDENSED 
TRUE FALSE Ctrl/Z EXPANDED 
1 0 
<Return> 
Note 


Entering ALL assumes that subsequent files are a positive response from 
the user, and no further prompting occurs. The routine UTIL$CQUAL _ 
FILE MATCH properly handles this response. Since UTIL$CQUAL _ 
CONFIRM_ACT does not contain context from a previous call, callers 

of this routine should not call UTIL$CQUAL_CONFIRM_ACT if the 
user has previously responded ALL unless the application needs explicit 
confirmation on certain items. 


The user can use any combination of uppercase and lowercase letters for word 
responses. Word responses can be abbreviated to one or more letters (for example, 
T, TR, or TRU for TRUE), but these abbreviations must be unique. 


After a valid response is received from the user, the procedure returns the 
current_form parameter. The current_form parameter contains the last form 
presented to the user if it was specified and write access is permitted. 


Condition Values Returned 


SS$ NORMAL Positive answer. 

LIB$ NEGANS Negative answer. 

UTIL$ QUIPRO Quit processing. 

UTIL$ QUICONACT Continue processing, but cease prompting. 
LIB$ INVARG Invalid argument list (no prompt strings). 
SS$ ACCVIO Access violation (on user routine address). 


Any unsuccessful return from RMS, SYS$ASSIGN, $QIOW, or from the user- 
supplied routine (other than RMS$ EOF). 
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Convert (CONVERT) Routines 


This chapter describes the CONVERT routines. These routines perform the 
functions of both the Convert and Convert/Reclaim utilities. 


6.1 Introduction to CONVERT Routines 


The Convert utility copies records from one or more files to an output file, 
changing the record format and file organization to that of the output file. You 
can invoke the functions of the Convert utility from within a program by calling 
the following series of three routines, in this order: 


1. CONV$PASS FILES 
2. CONV$PASS OPTIONS 
3. CONV$CONVERT 


Note that the application program should declare referenced constants and return 
status symbols as external symbols; these symbols are resolved upon linking with 
the utility shareable image. Also note that File Definition Language (F DL) errors 
may be returned to the calling program where applicable. 


The Convert/Recdaim utility reclaims empty buckets in Prolog 3 indexed files 
so new records can be written in them. You can invoke the functions of the 
Convert/Reclaim utility from within a program by calling the CONV$RECLAIM 
routine 


While these routines can be invoked within a single thread of a threaded process, 
the callable Convert utility is not a reentrant, thread safe utility. Multiple 
concurrent invocations of the callable Convert utility interface are not supported. 
These routines are not reentrant and cannot be called from the asynchronous 
system trap (AST) level. In addition, these routines require ASTs to remain 
enabled in order to function properly. 
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6.2 Using the CONVERT Routines: Examples 


Example 6-1 shows how to use the CONVERT routines in a Fortran program. 


Example 6-1 Using the CONVERT Routines in a Fortran Program 


* This program calls the routines that perform the 
* functions of the Convert Utility. It creates an 
* indexed output file named CUSTDATA.DAT from the 
* specifications in an FDL file named INDEXED.FDL. 
* The program then loads CUSTDATA.DAT with records 
* from the sequential file SEQ.DAT. No exception 
* file is created. This program also returns the 
* "BRIEF" CONVERT statistics. 
+ Program declarations 

IMPLICIT INTEGER*4 (A - Z) 
* Set up parameter list: number of options, CREATE, 
* NOSHARE, FAST LOAD, MERGE, APPEND, SORT, WORK FILES, 
* KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE, 
* NOEXIT, NOFIXED CONTROL, FILL BUCKETS, NOREAD CHECK, 
7 NOWRITE CHECK, FDL, and NOEXCEPTION. 
k 

INTEGER*4 OPTIONS (19) 

1 /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/ 
* Set up statistics list. Pass an array with the 
* number of statistics that you want. There are four 
* --- number of files, number of records, exception 
* records, and good records, in that order. 

INTEGER*4 STATSBLK(5) /4,0,0,0,0/ 
* Declare the file names. 

CHARACTER IN_FILE*7 /'SEQ.DAT’/, 

al OUT _FILE*12 /'CUSTDATA.DAT’/, 

1 FDL FILE*11 /' INDEXED. FDL! / 
* Call the routines in their required order. 

STATUS = CONVSPASS FILES (IN FILE, OUT FILE, FDL FILE) 

IF (.NOT. STATUS) CALL LIBSSTOP (%VAL(STATUS) ) 

STATUS = CONVSPASS OPTIONS (OPTIONS) 

IF (.NOT. STATUS) CALL LIBSSTOP (%VAL(STATUS) ) 

STATUS = CONVSCONVERT (STATSBLK) 

IF (.NOT. STATUS) CALL LIBSSTOP (%VAL(STATUS) ) 
* Display the statistics information. 

WRITE (6,1000) (STATSBLK(I) ,1=2,5) 
1000 FORMAT (1X,'Number of files processed: ',15/, 

1 1X,’Number of records: ',15/, 

1 1X,'Number of exception records: ',15/, 

1 1X,'Number of valid records: ',I5) 

END 


Example 6-2 shows how to use the advanced features of the CONVERT routines 
in aC program. 
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Example 6-2 Using the CONVERT Routines in a C Program 
/* 


** This module calls the routines that perform the functions 
** of the Convert utility. It creates an indexed output file 
** named CUSTDATA.DAT from the specifications in an FDL file 
** named INDEXED.FDL, and loads CUSTDATA.DAT with records from 
** the sequential file SEQ.DAT. No exception file is created. 
** This module also returns the CONVERT and SORT statistics 

** for each key that is loaded by utilizing the new callback 
** feature that is available through the CONVSCONVERT call. 

*/ 
#include <stdio> 

#include <descrip> 

#include <lib$routines> 

#include <convSroutines> 

#include <convdef> 

#include <starlet> 

/* 

** Allocate a statistics block structure using the template provided by 

** <convdef.h>. This structure will be passed to the CONVSCONVERT routine 
** to receive both the basic and extended statistics from CONVERT. The 

** fields returned to the structure from CONVERT are listed in table 5-1. 
kk 

** The number of statistics to be returned is passed as the first element 
** in the array. The value CONVSK_MAX STATISTICS will return the set of 

** basic statistics, while the value CONVS$K EXT STATISTICS will return all 
** statistics. 


of 

struct convS$statistics stats; 

/* 

** Main program (CONVSTAT) starts here 
*/ 


int CONVSTAT (void) 


SDESCRIPTOR (input file, "SEQ.DAT") ; 
SDESCRIPTOR (output file, "CUSTDATA.DAT") ; 
SDESCRIPTOR (fdl_ file, "“INDEXED.FDL") ; 


void callback (); 
int stat; 


/* 

** Allocate an options block structure using the template provided by 
** <convdef.h>. This structure will be passed to the CONVSPASS OPTIO 

NS 

** routine to indicate what options are to be used for the file convert. 
** The fields passed to the structure are listed in table 5-2. 

we 


struct convSoptions param list; 


(continued on next page) 
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Example 6-2 (Cont.) Using the CONVERT Routines in a C Program 


param_list.conv$] options count = CONVS$K MAX OPTIONS; 
param_list.conv$l create 1 
param_list.conv$l_ share = 0; 
param_list.conv$l fast = 1; 
param_list.conv$l merge = 0; 
param_list.conv$1 append = 05 
param _list.conv$l_ sort =: 1 
param_list.conv$1 work files = 2; 
param_list.conv$l key = 0; 
param_list.conv$1_pad = 0; 
param _list.conv$l pad character = 0; 
param_list.conv$1_ truncate = 0; 
param_list.conv$l exit = 0% 
param_list.conv$l_fixed_control = 0; 
param_list.conv$1 fill buckets = 0; 
param _list.conv$l_read_check = 0; 
param_list.conv$l_write_check = 0; 
param_list.conv$l_fdl = 1; 
param_list.conv$]_ exception = 0; 
param _list.conv$l_ prologue = 0; 
param _list.conv$l_ ignore prologue = 1; 
param_list.conv$]_ secondary S15 


/* 

** Init the number of statistics to be returned 

*/ 

stats.conv$l statistics count = CONVSK EXT STATISTICS; 
LIBSINIT_ TIMER () ; /* Start a timer */ 

/* 

** First call to pass all the file names 

ay 

stat = CONVSPASS FILES ( &input_ file, &output_file, &fdl file); 
if (! (stat & 1)) return stat; 

/* 

** Second call to pass particular options chosen as indicated in array. 
‘y 

stat = CONVSPASS OPTIONS ( &param list ); 

if (! (stat & 1)) return stat; 

/* 


** Final call to perform actual convert, passing statistics block and 
** callback routine address. 


*/ 

stat = CONVSCONVERT ( &stats, 0, &callback ); 

if (stat & 1 

/* 

** Successful Convert! Print out counters from statistics. 

*/ 

printf ("Number of files processed : $d\n", stats.conv$l_file count) ; 
printf ("Number of records : d\n", stats.conv$l_record_count) ; 
printf ("Number of exception records : %d\n", stats.conv$l_ except count) ; 
printf ("Number of valid records : d\n", stats.conv$l valid_count) ; 


LIBSSHOW TIMER () ; 


return stat; /* success or failure */ 


(continued on next page) 
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Example 6-2 (Cont.) Using the CONVERT Routines in a C Program 


void callback () 


int status, SYSSASCTIM(); 

int cvtflg = 1; 

static char date[15]; 

SDESCRIPTOR(out_date, date) ; 
printf ("Statistics for Key : d\n", stats.conv$l_ key number) ; 
printf (" Records Sorted : d\n", stats.conv$l rec out); 
printf (" Sort Nodes : d\n", stats.conv$l nodes) ; 
printf (" Work file allocation : %d\n", stats.conv$l wrk_alq); 
printf (" Initial Sort Runs : d\n", stats.conv$l_ ini runs) ; 
printf (" Merge Order : d\n", stats.conv$l_mrg order) ; 
printf (" Merge Passes : d\n", stats.conv$l_mrg passes) ; 
printf (" Sort Direct I0 : d\n", stats.conv$l_ sort dio count) ; 
printf (" Sort Buffered 10 : d\n", stats.conv$l sort bio count); 
status = SYSSASCTIM (0, &out_date, &stats.conv$q_sort_ elapsed time, cvtflg); 
if (! (status & 1)) LIBSSTOP (status) ; 
printf (" Sort Elapsed Time : s\n", date); 
status = SYSSASCTIM (0, &out_date, &stats.conv$q_sort_cpu_time, cvtflg) ; 
if (! (status & 1)) LIBSSTOP (status) ; 
printf (" Sort Cpu Time : s\n", date); 
printf (" Sort Page Faults : sd\n\n", stats.conv$l_ sort pf count); 
printf (" Load Direct I0 : d\n", stats.conv$l_load_dio count) ; 
printf (" Load Buffered 10 : d\n", stats.conv$l load bio count) ; 
status = SYSSASCTIM (0, &out_date, &stats.conv$q_load_elapsed time, cvtflg) ; 


if (! (status & 1)) LIBSSTOP (status) ; 
printf (" Load Elapsed Time : s\n", date); 
status = SYSSASCTIM (0, &out_date, &stats.conv$q load_cpu_time, cvtflg) ; 


if (! (status & 1)) LIBSSTOP (status) ; 


ep) 


printf (" Load Cpu Time : s\n", date); 
printf (" Load Page Faults : Sd\n\n", stats.conv$l load _pf count) ; 
return; 


Example 6-3 shows how to use the CONV$RECLAIM routine in a Fortran 
program. 


Example 6-3 Using the CONV$RECLAIM Routine in a Fortran Program 


This program calls the routine that performs the 
function of the Convert/Reclaim utility. It 
reclaims empty buckets from an indexed file named 
PROL3.DAT. It also returns all the CONVERT/RECLAIM 
statistics. 

Program declarations 


OO 


IMPLICIT INTEGER*4 (A - Z) 


Set up a statistics block. There are four -- data 
buckets scanned, data buckets reclaimed, index 
buckets reclaimed, total buckets reclaimed. 


INTEGER* 4 OUTSTATS (5) /4,0,0,0,0/ 
* Declare the input file. 
CHARACTER IN FILE*9 /'’PROL3.DAT’ / 


(continued on next page) 
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Example 6-3 (Cont.) Using the CONV$RECLAIM Routine in a Fortran Program 


* Call the routine. 


STATUS = CONVSRECLAIM (IN FILE, OUTSTATS) 
IF (.NOT. STATUS) CALL LIBSSTOP (%VAL (STATUS) ) 


* Display the statistics. 


WRITE (6,1000) (OUTSTATS (I) ,I=2,5) 
1000 FORMAT (1X,’Number of data buckets scanned: ',I15/, 


1 1X,'Number of data buckets reclaimed: ',15/, 
ih 1X,'Number of index buckets reclaimed: ',15/, 
1 1X,'’Total buckets reclaimed: ',I5) 

END 


Example 6-4 shows how to use the CONV$RECLAIM routine in a C program. 


Example 6-4 Using the CONV$RECLAIM Routine in a C Program 
/* 


** This module calls the routine that performs the 
** function of the CONVERT/RECLAIM utility. It reclaims 


** empty buckets from an indexed file named PROL3.DAT. 
kk 


** This module also returns and prints all of the 
** CONVERT/RECLAIM statistics. 

ve 

#include <stdio> 

#include <descrip> 


CONVREC () 


SDESCRIPTOR (filename, "PROL3.DAT");/* Provide your file name */ 


struct { int statistics count, /* must precede actual statistics */ 
scanned buckets, 
data_buckets_reclaimed, 
index buckets reclaimed, 
total_buckets reclaimed; } stats = 4 /* 4 statistic arguments */; 
int stat; 
/* 
** Perform actual operation. 
wf 
stat = CONVSRECLAIM ( &filename, &stats ); 
if (stat & 1) 
he 
** Successful RECLAIM. Now format and print the counts. 
of | 
printf ("Data buckets scanned : d\n", stats.scanned_buckets) ; 
printf ("Data buckets reclaimed : %d\n", stats.data_buckets reclaimed) ; 
printf ("Index buckets reclaimed : %d\n", stats.index_buckets reclaimed) ; 
printf ("Total buckets reclaimed : %d\n", stats.total_buckets reclaimed) ; 


return stat /* succes or failure */; 
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6.3 CONVERT Routines 
This section describes the individual CONVERT routines. 
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CONV$CONVERT—Initiate Conversion 


The CONV$CONVERT routine uses the Convert utility to perform the actual 
conversion begun with CONV$PASS FILES and CONV$PASS_ OPTIONS. 
Optionally, the routine can return statistics about the conversion. 


Note that the CONV$CONVERT routine may return appropriate File Definition 
Language (FDL) error messages to the calling program, where applicable. 


Format 
CONV$CONVERT [status_block_address] [,flags] [,callback_routine] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 


status_block_address 
OpenVMS usage: vector_longword_unsigned 


type: longword (unsigned) 
access: write only 
mechanism: by reference 


The conversion statistics. The status_block_address argument is the address of 
a variable-length array of longwords that receives statistics about the conversion. 


You can request conversion statistics using zero-based, symbolic offsets 
(CONV$K_) into the variablelength array of longwords that contains the 
statistics. The array is defined as a structure (CONV$STATISTICS) of named 
longwords (CONV $L_) to support access by high-level progamming languages. 


Table 6-1 lists the array elements by number and by symbol. The first element 
specifies the number of statistics to return by array order. For example, if you 
assign the symbol CONV$L_STATISTICS COUNT the value 2, the routine 
returns the statistics from the first two statistics elements: 


¢ Number of files converted 


¢ Number of records converted 


CONV-8 Convert (CONVERT) Routines 


Convert (CONVERT) Routines 


CONV$CONVERT 
Table 6-1 Conversion Statistics Array 
Array 
Element Field Name Description 
0 CONV$L_STATISTICS COUNT Number of statistics 
specified 
CONV$L_FILE_COUNT Number of files 
CONV$L_RECORD_COUNT Number of records 
3 CONV$L_EXCEPT_COUNT Number of exception 
record 
4 CONV$L_VALID_COUNT Number of valid 
records 
5 CONV$L_KEY_NUMBER Most recent key 
processed 
6 CONV$L_REC_OUT Number of records 
sorted 
7 CONV$L_NODES Nodes in sort tree 
8 CONV$L_WRK_ALQ Work file allocation 
9 CONV$L_INI_RUNS Initial dispersion runs 
10 CONV$L_MRG_ORDER Maximum merge order 
11 CONV$L_MRG_PASSES Number of merge 
passes 
12 CONV$L_SORT_DIO_COUNT Sort direct 10 
13 CONV$L_SORT_BIO_COUNT Sort buffered 10 
14 CONV$Q SORT _ELAPSED TIME Sort elapsed time 
15 CONV$Q_ SORT_CPU_TIME Sort CPU time 
16 CONV$L_SORT_PF_COUNT Number of page faults 
for sort 
17 CONV$L_LOAD_DIO_COUNT Load direct 1O 
18 CONV$L_LOAD_ BIO COUNT Load buffered 10 
19 CONV$Q_ LOAD ELAPSED TIME Load elapsed time 
20 CONV$Q_LOAD_CPU_TIME Load CPU time 
21 CONV$L_LOAD_PF_COUNT Number of page faults 
for load 
flags 
OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or masks) that control how the CONV$PASS FILES fdl_filespec 
argument is interpreted and how errors are signaled. The flags argument is 
the address of a longword containing control flags (or a mask). If you omit 
the flags argument or specify it as zero, no flags are set. The flags and their 


meanings are described in the following table: 
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Flag Function 


CONV$V_FDL_STRING Interprets the fdl_filespec argument supplied 
in the call to CONV$PASS FILES as an FDL 
specification in string form. By default, this 
argument is interpreted as the file name of an 


FDL file. 


Signals any error. By default, the status code is 
returned to the calling image. 


CONV$V_SIGNAL 


By default, an error status is returned rather than signaled. 


callback_routine 
OpenVMS usage: procedure 


type: procedure value 
access: read only 
mechanism: by reference 


Name of a user-supplied routine to process the statistics information. The 
callback_routine argument is the address of the procedure value of a user- 
supplied routine to call at the completion of each key load. 


Condition Values Returned 


SS$ NORMAL 
CONV$ BADBLK 
CONV$ BADLOGIC 
CONV$_BADSORT 
CONV$_CLOSEIN 
CONV$ CLOSEOUT 
CONV$_CONFQUAL 
CONV$_CREA_ERR 


CONV$_CREATEDSTM 


CONV$_DELPRI 
CONV$ DUP 
CONV$ EXTN_ERR 
CONV$ FATALEXC 
CONV$ FILLIM 
CONV$_IDX_LIM 
CONV$ ILL_KEY 
CONV$_ILL_VALUE 
CONV$_INP_FILES 
CONV$_INSVIRMEM 
CONV$ KEY 
CONV$ LOADIDX 
CONV$ NARG 


CONV-10 Convert (CONVERT) Routines 


Normal successful completion. 

Invalid option block. 

Internal logic error detected. 

Error trying to sort input file. 

Error closing file specification as input. 
Error closing file specification as output. 
Conflicting qualifiers. 

Error creating output file. 


File specification has been created in stream 
format. 


Cannot delete primary key. 
Duplicate key encountered. 
Unable to extend output file. 
Fatal exception encountered. 
Exceeded open file limit. 
Exceeded maximum index level. 
IIlegal key or value out of range. 
IIlegal parameter value. 

Too many input files. 
Insufficient virtual memory. 
Invalid record key. 

Error loading secondary index n. 
Wrong number of arguments. 


CONV$ NOKEY 
CONV$ NOTIDX 
CONV$ NOTSEQ 
CONV$ NOWILD 
CONV$ OPENEXC 
CONV$ OPENIN 
CONV$ OPENOUT 
CONV$ ORDER 
CONV$ PAD 


CONV$ PLV 
CONV$ PROERR 
CONV$ PROL_WRT 
CONV$ READERR 
CONV$ REX 
CONV$ RMS 
CONV$_RSK 
CONV$ RSZ 
CONV$ RTL 
CONV$ RTS 
CONV$ SEQ 
CONV$ UDF_BKS 
CONV$ UDF_BLK 
CONV$ VALERR 
CONV$ VFC 
CONV$ WRITEERR 
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No such key. 

File is not an indexed file. 

Output file is not a sequential file. 

No wildcard permitted. 

Error opening exception file specification. 
Error opening file specification as input. 
Error opening file specification as output. 
Routine called out of order. 


Packet Assembly/Disassembly (PAD) option 
ignored; output record format not fixed. 


Unsupported prolog version. 

Error reading prolog. 

Prolog write error. 

Error reading file specification. 

Record already exists. 

Record caused RMS severe error. 

Record shorter than primary key. 

Record does not fit in block/bucket. 

Record longer than maximum record length. 
Record too short for fixed record format file. 
Record not in order. 

Cannot convert UDF records into spanned file. 
Cannot fit UDF records into single block bucket. 
Specified value is out of legal range. 

Record too short to fill fixed part of VFC record. 
Error writing file specification. 
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CONV$PASS_FILES—Specify Conversion Files 


Format 


Returns 


Arguments 


The CONV$PASS FILES routine specifies a file to be converted using the 
CONV$CONVERT routine. 


CONV$PASS_FILES  input_filespec ,output_filespec [,fdl_filespec] 
[,exception_filespec] [, flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


input_filespec 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


The name of the file to be converted. The input_filespec argument is the 
address of a string descriptor pointing to the name of the file to be converted. 


output_filespec 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


The name of the file that receives the records from the input file. The output_ 
filespec argument is the address of a string descriptor pointing to the name of 
the file that receives the records from the input file. 


fdl_filespec 

OpenVMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


The name of the FDL file that defines the output file. The fdl_filespec argument 
is the address of a string descriptor pointing to the name of the FDL file. 
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exception_filespec 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


The name of the file that receives copies of records that cannot be written to 
the output file. The exception_filespec argument is the address of a string 
descriptor pointing to this name. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or masks) that control how the fdl_filespec argument is interpreted 

and how errors are signaled. The flags argument is the address of a longword 
containing the control flags (or mask). If you omit this argument or specify it as 
zero, no flags are set. If you specify a flag, it remains in effect until you explicitly 
reset it in a subsequent call toa CONVERT routine. 


The flags and their meanings are described in the following table: 


Flag Function 


CONV$V_FDL_STRING Interprets the fdl_filespec argument as an FDL 
specification in string form. By default, this 
argument is interpreted as a file name of an FDL 
file. 

CONV$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


By default, an error status is returned rather than signaled. 


The CONV$PASS FILES routine specifies a file to be converted using the 
CONV$CONVERT routine. A single call to CONV$PASS FILES allows you to 
specify an input file, an output file, an FDL file, and an exception file. If you 
have multiple input files, you must call CONV$PASS FILES once for each file. 
You need to specify only the input_filespec argument for the additional files, as 
follows: 


status = CONVSPASS FILES (input_filespec) 


The additional calls must immediately follow the original call that specified the 
output file specification. 


Wildcard characters are not allowed in the file specifications passed to the 
CONVERT routines. 
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Condition Values Returned 


SS$ NORMAL 
CONV$_INP_FILES 
CONV$_INSVIRMEM 
CONV$ NARG 
CONV$ ORDER 
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Normal successful completion. 
Too many input files. 
Insufficient virtual memory. 
Wrong number of arguments. 
Routine called out of order. 
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CONV$PASS_OPTIONS—Specify Processing Options 


Format 


Returns 


Arguments 


The CONV$PASS OPTIONS routine specifies which qualifiers are to be used by 
the Convert utility (CONVERT). 


CONV$PASS_OPTIONS _ [parameter_list_address] [,flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


parameter_list_address 
OpenVMS usage: vector_longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Address of a variable-length array of longwords used to specify the CONVERT 
qualifiers. The array is symbolically defined as a structure (CONV$OPTIONS) 
that you can access in one of the following ways: 


e Asan array of named longwords using zero-based symbols (CONV$L_... ) 
e Asan array using zero-based offsets (CONV$K_... ) 


The first longword in the array (CONV$L_OPTIONS COUNT) specifies the 
number of elements in the array, and each remaining element is associated with 
a CONVERT qualifier, as shown in Table 6-2. You can use the first element 

to assign values to the first n CONVERT qualifiers—where n is the value 

of CONV$L_OPTIONS COUNT—and take default values for the remaining 
qualifiers. For example, to assign values to only the first three qualifiers and to 
take the default value for the remaining qualifiers, specify CONV$L_OPTIONS_ 
COUNT=3. This effectively changes the size of the array to include only the first 
three elements, as follows, which have values you specify: 


e /CREATE 

e /SHARE 

* /FAST_LOAD 

The remaining qualifiers take the default values depicted in Table 6-2. 


To assign individual values to the CONVERT qualifiers, access the array and 
specify the desired value (1 or 0). See the OpenVMS Record Management Utilities 
Reference Manual for detailed descriptions of the CONVERT qualifiers. 
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If you do not specify parameter _list_address, your program effectively sends 
the routine all of the default values listed in Table 6-2. 


Table 6-2 CONVERT Qualifiers 


Longword 
Element Default Qualifier 
Number Symbolic Value Value Default Value 
0 CONV$L_OPTIONS COUNT None Not applicable 
1 CONV$L_CREATE 1 /CREATE 
2 CONV$L_SHARE 0 /NOSHARE 
3 CONV$L_FAST 1 /FAST_LOAD 
4 CONV$L_MERGE 0 /NOMERGE 
5 CONV$L_APPEND 0 /NOAPPEND 
6 CONV$L_SORT 1 /SORT 
7 CONV$L_WORK_FILES 2 /WORK_ 
FILES=2 
8 CONV$L_KEY 0 /KEY =0 
9 CONV$L_PAD 0 /NOPAD 
10 CONV$L_PAD_CHARACTER o! Pad character =0 
11 CONV$L_TRUNCATE 0 /NOTRUNCATE 
12 CONV$L_EXIT 0 /NOEXIT 
13 CONV$L_FIXED_CONTROL 0 /NOFIXED_ 
CONTROL 
14 CONV$L_FILL_BUCKETS 0 /NOFILL_ 
BUCKETS 
15 CONV$L_READ_CHECK 0 /NOREAD_ 
CHECK 
16 CONV$L_WRITE_CHECK 0 /NOWRITE _ 
CHECK 
17 CONV$L_FDL 0 /NOFDL 
18 CONV$L_EXCEPTION 0 /NOEXCEPTION 
19 CONV$L_PROLOGUE None /PROLOGUE =2 
20 CONV$L_IGNORE_PROLOGUE 0 Not applicable 
21 CONV$L_SECONDARY 1 SECONDARY =1 


1Null character. To specify non-null pad character, insert ASCII value of desired pad character. 
2System or process default setting. 


If you specify /EXIT and the utility encounters an exception record, CONVERT 
returns with a fatal exception status. 


If you specify an FDL file specification in the CONV$PASS FILES routine, 
you must place a 1 in the FDL longword. If you also specify an exceptions file 
specification in the CONV$PASS FILES routine, you must place a 1 in the 
EXCEPTION longword. You may specify either, both, or neither of these files, 
but the values in the CONV$PASS_FILES call must match the values in the 


parameter list. If they do not, the routine returns an error. 
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The PROLOG longword overrides the KEY PROLOG attribute supplied by the 
FDL file. If you use the PROLOG longword, enter one of the following values: 


e« The value 0 (default) specifies the system or process prolog type. 


e The value 2 specifies a Prolog 1 or 2 file in all instances, even when 
circumstances would allow you to create a Prolog 3 file. 


e The value 3 specifies a Prolog 3 file. If a Prolog 3 file is not allowed, you want 
the conversion to fail. 


If the size of the options block that you pass to CONV$PASS OPTIONS 
includes the SECONDARY longword value, then you must specify a value for 
the |GNORE_PROLOGUE field. 


This field is used in conjunction with the PROLOGUE offset to determine if the 
prologue version of the output file is to be taken from a passed FDL, the input 
file, the process default or system default, or from the options block itself. 


A value of 0 (zero) for the |GNORE_PROLOGUE field indicates that the prologue 
version of the output file is to be taken from the PROLOGUE value specified in 
the options block. 


If the PROLOGUE value in the options block contains a 0 (zero), the process 
default or system default prologue version will be used. This will override the 
prologue version specified in an FDL file or in the input file’s characteristics. 


A value of 1 (one) for the |GNORE_ PROLOGUE field implies that the prologue 
version of the output file will come from the FDL file (if specified) or from the 
input file’s characteristics. 
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Description 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or masks) that control how the fdl_filespec argument, used in calls to the 
CONV$PASS FILES routine, is interpreted and how errors are signaled. The 
flags argument is the address of a longword containing the control flags (or a 
mask). If you omit this argument or specify it as zero, no flags are set. If you 
specify a flag, it remains in effect until you explicitly reset it in a subsequent call 
toa CONVERT routine. 


The flags and their meanings are described in the following table: 


Flag Function 


CONV$V_FDL_STRING Interprets the fdl_filespec argument supplied 
in the call to CONV$PASS FILES as an FDL 
specification in string form. By default, this 
argument is interpreted as the file name of an 
FDL file. 


FDL$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


By default, an error status is returned rather than signaled. 


You can use an options array to generate programmatic CONVERT commands. 
For example, you can generate the following programmatic CONVERT command 
by configuring the options array described by the pseudocode that follows the 
example command line: 


$ CONVERT/FAST_LOAD/SORT/WORK_FILES=6 /EXIT 

OPTIONS ARRAY [12] Allocate a 13-cell array} 
OPTIONS[0] = 12 Number of options] 

OPTIONS[1] = 1 Specifies the /CREATE option} 
OPTIONS[2] = 0 Specifies the /NOSHARE option} 
OPTIONS[3] = 1 Specifies the /FAST LOAD option} 
OPTIONS [4 = 0 Specifies the /NOMERGE option} 
OPTIONS [5 = 0 Specifies the /NOAPPEND option} 
OPTIONS[6] = 1 Specifies the /SORT option} 
OPTIONS[7] = 6 Specifies the /WORK FILES=6 option} 
OPTIONS[8] = 0 Specifies the /KEY=0 option 
OPTIONS[9] = 0 Specifies the /NOPAD option 
OPTIONS[10] = 0 Specifies the null pad character 
OPTIONS [11] = 0 Specifies the /NOTRUNCATE option 
OPTIONS[12] = 1 Specifies the /EXIT option} 
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Condition Values Returned 


SS$ NORMAL Normal successful completion. 

CONV$ BADBLK Invalid option block. 

CONV$ CONFQUAL Conflicting qualifiers. 

CONV$ INSVIRMEM Insufficient virtual memory. 

CONV$ NARG Wrong number of arguments. 

CONV$ OPENEXC Error opening exception file file specification. 
CONV$ ORDER Routine called out of order. 
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CONV$RECLAIM—Invoke Convert/Reclaim Utility 


Format 


Returns 


Arguments 


The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim 
utility. 


CONV$RECLAIM _ input_filespec [,statistics_blk] [,flags] [kKey_number] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


input_filespec 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


Name of the Prolog 3 indexed file to be reclaimed. The input_filespec argument 
is the address of a string descriptor pointing to the name of the Prolog 3 indexed 
file. 


statistics_blk 
OpenVMS usage: vector_longword_unsigned 


type: longword (unsigned) 
access: modify 
mechanism: by reference 


Bucket reclamation statistics. The statistics blk argument is the address 

of a variable-length array of longwords that receives statistics on the bucket 
reclamation. You can choose which statistics you want returned by specifying a 
number in the first element of the array. This number determines how many of 
the four possible statistics the routine returns. 


You can request bucket reclamation statistics using symbolic names or numeric 
offsets into the variable-length array of longwords that contains the statistics. 
The array is defined as a structure of named longwords (RECL$STATISTICS) to 
support access by high-level progamming languages. 
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Table 6-3 lists the array elements by number and by symbol. The first element 
specifies one or more statistics by array order. For example, if you assign the 
symbol RECL$L_STATISTICS COUNT the value 3, the routine returns the 
statistics from the first three statistics elements: 


e Data buckets scanned 
e Data buckets reclaimed 


e Index buckets reclaimed 


Table 6-3 Bucket Reclamation Statistics Array 


Array 

Element Field Name Description 
0 RECL$L_STATISTICS COUNT Number of statistics specified 
1 RECL$L_SCAN_COUNT Data buckets scanned 
2 RECL$L_DATA_COUNT Data buckets reclaimed 
3 RECL$L_INDEX_COUNT Index buckets reclaimed 
4 RECL$L_TOTAL_COUNT Total buckets reclaimed 

flags 

OpenVMS usage: mask_longword 

type: longword (unsigned) 

access: read only 

mechanism: by reference 


Flags (or masks) that control how the fdl_filespec argument, used in calls to the 
CONV$PASS FILES routine, is interpreted and how errors are signaled. The 
flags argument is the address of a longword containing control flags (or a mask). 
If you omit the flags argument or specify it as zero, no flags are set. The flag is 
defined as follows: 


CONV$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


By default, an error status is returned rather than signaled. 


key_number 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


The optional key_number argument permits the calling program to selectively 
reclaim buckets by key number. If the calling program omits this argument or 
passes a NULL value in the argument, all buckets are reclaimed, without regard 
to key designation. If the calling program passes a valid key number as the value 
for this argument, the routine reclaims only the buckets for the specified key. 
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Condition Values Returned 


SS$ NORMAL 
CONV$ BADLOGIC 
CONV$_INSVIRMEM 
CONV$_INVBKT 
CONV$ NOTIDX 
CONV$ NOWILD 
CONV$_OPENIN 
CONV$ PLV 

CONV$ PROERR 
CONV$ PROL_WRT 
CONV$ READERR 
CONV$ WRITEERR 
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Normal successful completion. 
Internal logic error detected. 
Insufficient virtual memory. 
Invalid bucket at VBN n. 

File is not an indexed file. 

No wildcard permitted. 

Error opening file specification as input. 
Unsupported prolog version. 
Error reading prolog. 

Prolog write error. 

Error reading file specification. 
Error writing output file. 
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Data Compression/Expansion (DCX) Routines 


The set of routines described in this chapter comprises the Data 
Compression/E xpansion (DCX) facility. There is no DCL-level interface to 
this facility, nor is there a DCX utility. 


7.1 Introduction to DCX Routines 


Using the DCX routines described in this chapter, you can decrease the size of 
text, binary data, images, and any other type of data. Compressed data uses less 
space, but there is a trade-off in terms of access time to the data. Compressed 
data must first be expanded to its original state before it is usable. Thus, 
infrequently accessed data makes a good candidate for data compression. 


The DCX facility provides routines that analyze and compress data records 
and expand the compressed records to their original state. In this process, no 
information is lost. A data record that has been compressed and then expanded 
is in the same state as it was before it was compressed. 


Most collections of data can be reduced in size by DCX. However, there is no 
guarantee that the size of an individual data record will always be smaller after 
compression; in fact, some may grow larger. 


The DCX facility allows for the independent analysis, compression, and expansion 
of more than one stream of data records at the same time. This capability is 
provided by means of a “context variable,” which is an argument in each DCX 
routine. Most applications have no need for this capability; for these applications, 
there is a single context variable. 


Some of the DCX routines make calls to various Run-Time Library (RTL) 
routines, for example, LIB$GET_VM. If any of these RTL routines fails, a return 
status code indicating the cause of the failure is returned. In such a case, you 
must refer to the documentation of the appropriate RTL routine to determine the 
cause of the failure. The status codes documented in this chapter are primarily 
DCX status codes. 


Note also that the application program should declare referenced constants and 
return status symbols as external symbols; these symbols are resolved upon 
linking with the utility shareable image. 


7.1.1 Compression Routines 
Compressing a file with the DCX routines involves the following steps: 


1. Initialize an analysis work area—Use the DCX$ANALY ZE_INIT routine to 
initialize a work area for analyzing the records. The first (and, typically, the 
only) argument passed to DCX$ANALYZE_INIT is an integer variable for 
storing the context value. The DCX facility assigns a value to the context 
variable and associates the value with the created work area. Each time you 
want to analyze a record in that area, specify the associated context variable. 
You can analyze two or more files at once by creating a different work area 
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for each file, giving each area a different context variable, and analyzing the 
records of each file in the appropriate work area. 


2. Analyze the records in the file—Use the DCX$ANALYZE_DATA routine to 
pass each record in the file to an analysis work area. During analysis, the 
DCX facility gathers information that DCX$MAKE_MAP uses to create the 
compression/expansion function for the file. To ensure that the first byte of 
each record is passed to the DCX facility rather than being interpreted as a 
carriage control, specify CARRIAGECONTROL =NONE when you open the 
file to be compressed. 


3. Create the compression/expansion function—Use the DCX$MAKE_ MAP 
routine to create the compression/expansion function. You pass DCX$MAKE _ 
MAP a context variable, and DCX$MAKE_MAP uses the information stored 
in the associated work area to compute a compression/expansion function for 
the records being compressed. If DCX$MAKE_MAP returns a status value of 
DCX$ AGAIN, repeat Steps 2 and 3 until DCX$MAKE_MAP returns a status 
of DCX$ NORMAL, indicating that a compression/expansion function has 
been created. 


In Example 7-1, the integer function GET_MAP analyzes each record in 

the file to be compressed and invokes DCX$MAKE_MAP to create the 
compression/expansion function. The function value of GET_MAP is the 
return status of DCX$MAKE_MAP, and the address and length of the 
compression/expansion function are returned in the GET_MAP argument list. 
The main program, COMPRESS FILES, invokes the GET_MAP function, 
examines its function value, and, if necessary, invokes the GET_MAP function 
again (see the ANALY ZE DATA program section). 


4. Clean up the analysis work area—Use the DCX$ANALYZE DONE routine 
to delete a work area. Identify the work area to be deleted by passing 
DCX$ANALYZE_ DONE routine a context variable. 


5. Save the compression/expansion function—You cannot expand compressed 
records without the compression/expansion function. Therefore, before 
compressing the records, write the compression/expansion function to the file 
that will contain the compressed records. 


If your programming language cannot use an address directly, pass 
the address of the compression/expansion function to a subprogram 
(WRITE_MAP in Example 7-1). Pass the subprogram the length of the 
compression/expansion function as well. 


In the subprogram, declare the dummy argument corresponding to the 
function address as a one-dimensional, adjustable, byte array. Declare the 
dummy argument corresponding to the function length as an integer, and use 
it to dimension the adjustable array. Write the function length and the array 
containing the function to the file that is to contain the compressed records. 
(The length must be stored so that you can read the function from the file 
using unformatted I/O; see Section 7.1.2.) 


6. Compress each record—Use the DCX$COMPRESS INIT routine to initialize 
a compression work area. Specify a context variable for the compression area 
just as for the analysis area. 


Use the DCX$COMPRESS DATA routine to compress each record. As you 
compress each record, use unformatted I/O to write the compressed record 
to the file containing the compression/expansion function. For each record, 
write the length of the record and the substring containing the record. See 
the COMPRESS DATA section in Example 7-1. (The length is stored with 
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the substring so that you can read the compressed record from the file using 
unformatted |/O; see Section 7.1.2.) 


7. Use DCX$COMPRESS DONE to delete the work area created by 
DCX$COMPRESS INIT. Identify the work area to be deleted by passing 
DCX$COMPRESS DATA a context variable. Use LIB$FREE_VM to free the 
virtual memory that DCX$MAKE_MAP used for the compression/expansion 
function. 


7.1.2 Expansion Routines 
Expanding a file with the DCX routines involves the following steps: 


1. Read the compression/expansion function—When reading the 
compression/expansion function from the compressed file, do not make 
any assumptions about the function's size. The best practice is to read 
the length of the function from the compressed file and then invoke the 
LIB$GET_VM routine to get the necessary amount of storage for the function. 
The LIB$GET_VM routine returns the address of the first byte of the storage 
area. 


If your programming language cannot use an address directly, pass the 
address of the storage area to a subprogram. Pass the subprogram the length 
of the compression/expansion function as well. 


In the subprogram, declare the dummy argument corresponding to the 
storage address as a one-dimensional, adjustable, byte array. Declare the 
dummy argument corresponding to the function length as an integer and 
use it to dimension the adjustable array. Read the compression/expansion 
function from the compressed file into the dummy array. Because the 
compression/expansion function is stored in the subprogram, do not return to 
the main program until you have expanded all of the compressed records. 


2. Initialize an expansion work area—Use the DCX$E XPAND INIT routine to 
initialize a work area for expanding the records. The first argument passed 
to DCX$EXPAND_INIT is an integer variable to contain a context value 
(see step 1 in Section 7.1.1). The second argument is the address of the 
compression/expansion function. 


3. Expand the records—Use the DCX$E XPAND_DATA routine to expand each 
record. 


4. Clean up the work area—Use the DCX$EXPAND_DONE routine to delete 
an expansion work area. | dentify the work area to be deleted by passing 
DCX$EXPAND_ DONE a context variable 


7.2 Using the DCX Routines: Examples 


Example 7-1 shows how to use the callable DCX routines to compress a file in a 
HP Fortran program. 


Example 7-2 expands a compressed file. The first record of the compressed file is 
an integer containing the number of bytes in the compression/expansion function. 
The second record is the compression/expansion function. The remainder of the 
file contains the compressed records. Each compressed record is stored as two 
records: an integer containing the length of the record and a substring containing 
the record. 
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Example 7-1 Compressing a File in a HP Fortran Program 


PROGRAM COMPRESS FILES 
! COMPRESSION OF FILES 


! status variable 
INTEGER STATUS, 


2 IOSTAT, 
2 10 OK, 
2 STATUS OK 


PARAMETER (IO OK = 0) 
PARAMETER (STATUS OK = 1) 


INCLUDE ' ($FORDEF) ' 
EXTERNAL DCX$ AGAIN 


! context variable 

INTEGER CONTEXT 

! compression/expansion function 
INTEGER MAP, 

2 MAP LEN 


! normal file name, length, and logical unit number 
CHARACTER*256 NORM NAME 

INTEGER*2 NORM LEN 

INTEGER NORM_LUN 
! compressed file name, length, and logical unit number 
CHARACTER*256 COMP NAME 

INTEGER*2 COMP LEN 

INTEGER COMP_LUN 


! Logical end-of-file 

LOGICAL EOF 

! record buffers; 32764 is maximum record size 
CHARACTER*32764 RECORD, 


2 RECORD2 
INTEGER RECORD LEN, 
2 RECORD2_LEN 


! user routine 
INTEGER GET MAP, 
2 WRITE MAP 


! Library procedures 
INTEGER DCXSANALYZE INIT, 
2 DCXSANALYZE_ DONE, 
DCXSCOMPRESS INIT, 
DCXSCOMPRESS DATA, 
DCXSCOMPRESS DONE, 
LIBSGET_INPUT, 
IBSGET LUN, 
IBSFREE_VM 


E 
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! get name of file to be compressed and open it 
STATUS = LIBSGET_INPUT (NORM NAME, 

2 'File to compress: ', 

2 NORM_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
STATUS = LIBSGET LUN (NORM LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
OPEN (UNIT = NORM LUN, 


2 FILE = NORM NAME (1:NORM LEN) , 
2 CARRIAGECONTROL = ‘NONE’, 
2 STATUS = 'OLD’) 


(continued on next page) 
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Example 7-1 (Cont.) Compressing a File in a HP Fortran Program 


KREKKKKKKKKKE 


| 
! ANALYZE DATA 
! KRKEKKKKKEKEKE 

! initialize work area 

STATUS = DCXSANALYZE INIT (CONTEXT) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
! get compression/expansion function (map) 
STATUS = GET MAP (NORM LUN, 


2 CONTEXT, 
2 MAP, 
2 MAP_LEN 


DO WHILE (STATUS .EQ. %LOC(DCX$ AGAIN) ) 
! go back to beginning of file 
REWIND (UNIT = NORM LUN 
! try map again 
STATUS = GET MAP (NORM LUN, 


2 CONTEXT, 

2 MAP, 

2 MAP LEN) 
END DO 


IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
! clean up work area 

STATUS = DCXSANALYZE DONE (CONTEXT) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 


KEKKKKKKKKKKK 


| 
! COMPRESS DATA 
| RRR KKKEKKKKKEK 

! go back to beginning of file to be compressed 

REWIND (UNIT = NORM_LUN) 

! open file to hold compressed records 

STATUS = LIBSGET LUN (COMP LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

STATUS = LIBSGET_ INPUT (COMP_NAME, 

2 'File for compressed records: ', 
2 COMP_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

OPEN (UNIT = COMP LUN, 


2 FILE = COMP _NAME(1:COMP LEN), 
2 STATUS = ‘NEW’, 
2 FORM = 'UNFORMATTED’ ) 


! initialize work area 

STATUS = DCXSCOMPRESS INIT (CONTEXT, 

2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

! write compression/expansion function to new file 
CALL WRITE MAP (COMP LUN, 

2 SVAL (MAP) , 

2 MAP LEN) 


(continued on next page) 
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Example 7-1 (Cont.) Compressing a File in a HP Fortran Program 


! read record from file to be compressed 


HOF = .FALSE. 

READ (UNIT = NORM LUN, 

2 FMT = ‘(Q,A)', 

2 IOSTAT = IOSTAT) RECORD LEN, 

2 RECORD (1:RECORD_ LEN) 


IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FOR$ ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 


ELSE 
EOF = .TRUE. 
STATUS = STATUS OK 
END IF 

END IF 


DO WHILE (.NOT. EOF) 
! compress the record 
STATUS = DCXSCOMPRESS DATA (CONTEXT, 


2 RECORD (1:RECORD LEN), 
2 RECORD2, 
2 RECORD2_ LEN) 


IF (.NOT. STATUS) CALL LIBSSIGNAL ($VAL (STATUS) ) 
! write compressed record to new file 

WRITE (UNIT = COMP_LUN) RECORD2_ LEN 

WRITE (UNIT = COMP_LUN) RECORD2 (1:RECORD2 LEN) 
! read from file to be compressed 

READ (UNIT = NORM LUN, 


2 FMT = ‘(Q,A)', 
2 IOSTAT = IOSTAT) RECORD LEN, 
2 RECORD (1:RECORD_LEN) 
IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 


IF (STATUS .NE. FORS ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 


ELSE 
EOF = .TRUE. 
STATUS = STATUS OK 
END IF 
END IF 
END DO 


! close files and clean up work area 
CLOSE (NORM LUN) 
CLOSE (COMP_LUN) 
STATUS = LIBSFREE VM (MAP LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
STATUS = DCX$COMPRESS DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 


END 

INTEGER FUNCTION GET MAP (LUN, ! passed 

2 CONTEXT, ! passed 

2 MAP, ! returned 
2 MAP LEN) ! returned 


! Analyzes records in file opened on logical 
! unit LUN and then attempts to create a 

! compression/expansion function using 

! DCXSMAKE MAP. 


(continued on next page) 
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Example 


Data Compression/Expansion (DCX) Routines 
7.2 Using the DCX Routines: Examples 


7-1 (Cont.) Compressing a File in a HP Fortran Program 


! dummy arguments 


! context 
! logical 


! compres 


! status 

INTEGER S 
2 a 
2 I 
2 S 


variable 


INTEGER CONTEXT 


unit number 


INTEGER LUN 


sion/expansion function 


INTEGER MAP, 
2 MAP_LEN 


variable 
TATUS, 
OSTAT, 

0 OK, 
TATUS OK 


PARAMETER (IO OK = 0) 
PARAMETER (STATUS OK = 1) 


INCLUDE ' 


! Logical 


(SFORDEF) ' 


end-of-file 


LOGICAL EOF 


! record 


buffer; 32764 is the maximum record size 


CHARACTER*32764 RECORD 
INTEGER RECORD LEN 


! library procedures 


INTEGER DCXSANALYZE DATA, 

2 DCXS$MAKE MAP 

! analyze records 

EOF = .FALSE. 

READ (UNIT = LUN, 

2 FMT = ‘(Q,A)', 

2 IOSTAT = IOSTAT) RECORD LEN, RECORD 


IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 
IF (STATUS .NE. FORS ENDDURREA) THEN 


CALL 
ELSE 
EOF 
STAT 
END 
END IF 


DO WHILE 
STATUS 
2 
IF (.NO 


LIBSSIGNAL (%VAL(STATUS) ) 
= .TRUE. 
US = STATUS OK 
IF 
(.NOT. EOF) 
= DCXSANALYZE DATA (CONTEXT, 


RECORD (1:RECORD_ LEN) ) 
T. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 


READ (UNIT = LUN, 


2 F 
2 He 
IF (10S 
CALL 


T= '(Q,A)', 

OSTAT = IOSTAT) RECORD LEN, RECORD 
TAT .NE. IO OK) THEN 

ERRSNS (,,,,STATUS) 


IF (STATUS .NE. FORS ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
ELSE 
EOF = .TRUE. 
STATUS = STATUS OK 
END IF 

END IF 

END DO 


(continued on next page) 
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Data Compression/Expansion (DCX) Routines 
7.2 Using the DCX Routines: Examples 


Example 7-1 (Cont.) Compressing a File in a HP Fortran Program 


STATUS = DCXSMAKE MAP (CONTEXT, 


2 MAP, 

2 MAP_LEN) 

GET MAP = STATUS 

END 

SUBROUTINE WRITE MAP (LUN, ! passed 
2 MAP, ! passed 
2 MAP LEN) ! passed 


IMPLICIT INTEGER (A-Z) 
! write compression/expansion function 
! to file of compressed data 


! dummy arguments 


INTEGER LUN, ! logical unit of file 
2 MAP_LEN ! length of function 
BYTE MAP (MAP_LEN) ! compression/expansion function 


! write map length 
WRITE (UNIT = LUN) MAP LEN 


! write map 
WRITE (UNIT = LUN) MAP 
END 


Example 7-2 shows how to expand a compressed file in a HP Fortran program. 


Example 7-2 Expanding a Compressed File in a HP Fortran Program 


PROGRAM EXPAND FILES 
IMPLICIT INTEGER (A-Z) 
! EXPANSION OF COMPRESSED FILES 


! file names, lengths, and logical unit numbers 
CHARACTER*256 OLD FILE, 

2 NEW FILE 

INTEGER*2 OLD LEN, 

2 NEW LEN 

INTEGER OLD LUN, 

2 NEW LUN 

length of compression/expansion function 


INTEGER MAP, 
2 MAP_LEN 


! user routine 
EXTERNAL EXPAND DATA 


! library procedures 
INTEGER LIBSGET_LUN, 


2 LIBSGET_INPUT, 
2 LIBSGET_VM, 
2 LIBSFREE VM 


(continued on next page) 
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Data Compression/Expansion (DCX) Routines 
7.2 Using the DCX Routines: Examples 


Example 7-2 (Cont.) Expanding a Compressed File in a HP Fortran Program 


! open file to expand 

STATUS = LIBSGET LUN (OLD LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
STATUS = LIBSGET_ INPUT (OLD FILE, 

2 ‘File to expand: ', 

2 OLD_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
OPEN (UNIT = OLD LUN, 


2 STATUS = ‘OLD’, 
2 FILE = OLD FILE(1:OLD LEN), 
2 FORM = 'UNFORMATTED’ ) 


! open file to hold expanded data 

STATUS = LIBSGET LUN (NEW LUN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

STATUS = LIBSGET_INPUT (NEW FILE, 

2 ‘File to hold expanded data: ', 
2 NEW_LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 

OPEN (UNIT = NEW LUN, 


2 STATUS = ‘NEW’, 
2 CARRIAGECONTROL = ‘LIST’, 
2 FILE = NEW FILE(1:NEW LEN) ) 


! expand file 

! get length of compression/expansion function 
READ (UNIT = OLD LUN) MAP LEN 

STATUS = LIBSGET VM (MAP LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
! expand records 

CALL EXPAND DATA (%VAL(MAP) , 


2 MAP LEN, ! length of function 
2 OLD LUN, ! compressed data file 
2 NEW_LUN) ! expanded data file 


! delete virtual memory used for function 
STATUS = LIBSFREE VM (MAP LEN, 


2 MAP) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
END 

SUBROUTINE EXPAND DATA (MAP, ! passed 

2 MAP_LEN, ! passed 

2 OLD LUN, ! passed 

2 NEW LUN) ! passed 


! expand data program 


! dummy arguments 

INTEGER MAP LEN, ! length of expansion function 

2 OLD LUN, ! logical unit of compressed file 
2 NEW LUN ! logical unit of expanded file 
BYTE MAP(MAP LEN) ! array containing the function 


! status variables 
INTEGER STATUS, 


2 IOSTAT, 
2 10 OK, 
2 STATUS OK 


PARAMETER (10 OK = 0) 
PARAMETER (STATUS OK = 1) 


INCLUDE ' (SFORDEF) ' 


(continued on next page) 
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Data Compression/Expansion (DCX) Routines 
7.2 Using the DCX Routines: Examples 


Example 7-2 (Cont.) Expanding a Compressed File in a HP Fortran Program 


! context variable 
INTEGER CONTEXT 


! logical end_of file 
LOGICAL EOF 

! record buffers 
CHARACTER* 32764 RECORD, 


2 RECORD2 
INTEGER RECORD LEN, 
2 RECORD2_LEN 


! library procedures 

INTEGER DCX$EXPAND INIT, 
2 DCXSEXPAND DATA, 
2 DCXSEXPAND_ DONE 


! read data compression/expansion function 

READ (UNIT = OLD_ LUN) MAP 

! initialize work area 

STATUS = DCXSEXPAND_INIT (CONTEXT, 

2 %SLOC (MAP (1) ) ) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! expand records 

EOF = .FALSE. 

! read length of compressed record 

READ (UNIT = OLD LUN, 


2 IOSTAT = IOSTAT) RECORD LEN 
IF (IOSTAT .NE. IO OK) THEN 
CALL ERRSNS (,,,,STATUS) 


IF (STATUS .NE. FORS ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
ELSE 


EOF = .TRUE. 
STATUS = STATUS OK 
END IF 

END IF 


DO WHILE (.NOT. EOF) 
! read compressed record 
READ (UNIT = OLD LUN) RECORD (1:RECORD LEN) 
! expand record 
STATUS = DCXSEXPAND DATA (CONTEXT, 


2 RECORD (1:RECORD_ LEN) , 
2 RECORD2, 
2 RECORD2_ LEN) 


IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
! write expanded record to new file 

WRITE (UNIT = NEW LUN, 

2 FMT = ‘(A)') RECORD2(1:RECORD2_LEN) 

! read length of compressed record 

READ (UNIT = OLD LUN, 


2 IOSTAT = IOSTAT) RECORD LEN 
IF (IOSTAT .NE. I0 OK) THEN 
CALL ERRSNS (,,,,STATUS) 


IF (STATUS .NE. FORS ENDDURREA) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
ELSE 
EOF = .TRUE. 
STATUS = STATUS OK 
END IF 

END IF 
END DO 
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Data Compression/Expansion (DCX) Routines 
7.2 Using the DCX Routines: Examples 


Example 7-2 (Cont.) Expanding a Compressed File in a HP Fortran Program 


! clean up work area 

STATUS = DCXSEXPAND DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL(STATUS) ) 
END 


7.3 DCX Routines 


This section describes the individual DCX routines. 
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DCX$ANALYZE_ DATA 


DCX$ANALYZE_DATA—Perform Statistical Analysis on a Data 
Record 


The DCX$ANALY ZE_DATA routine performs statistical analysis on a data record. 
The results of the analysis are accumulated internally in the context area and are 
used by the DCX$MAKE_MAP routine to compute the mapping function. 


Format 
DCX$ANALYZE DATA context ,record 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value identifying the data stream that DCX$ANALYZE_ DATA analyzes. 

The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneous! y. 


record 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Record to be analyzed. DCX$ANALY ZE_DATA reads the record argument, 
which is the address of a descriptor for the record string. The maximum length of 
the record string is 65,535 characters. 
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DCX$ANALYZE_ DATA 


Description 


The DCX$ANALY ZE_DATA routine performs statistical analysis on a single data 
record. This routine is called once for each data record to be analyzed. 


During analysis, the DCX facility gathers information that DCX$MAKE_MAP 
uses to create the compression/expansion function for the file. After the data 
records have been analyzed, call the DCX$MAKE_MAP routine. Upon receiving 
the DCX$ AGAIN status code from DCX$MAKE_MAP, you must again analyze 
the same data records (in the same order) using DCX$ANALY ZE_DATA and 
then call DCX$MAKE_MAP again. On the second iteration, DCX$MAKE_MAP 
returns the DCX$ NORMAL status code, and the data analysis is complete. 


Condition Values Returned 


DCX$ INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


DCX$ NORMAL Normal successful completion. 


This routine also returns any condition values returned by LIB$ANALYZE _ 
SDESC R2. 
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DCX$ANALYZE DONE 


DCX$ANALYZE_DONE—Specify Analysis Completed 


The DCX$ANALY ZE_DONE routine deletes the context area and sets the context 
variable to zero, undoing the work of the DCX$ANALY ZE_INIT routine. 


Call DCX$ANALYZE_DONE after data records have been analyzed and the 
DCX$MAKE_MAP routine has created the map. 


Format 
DCX$ANALYZE DONE context 
Returns 
OpenVMS usage: cond_value 
type: longword 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Argument 
context 
OpenVMS usage: context 
type: longword 
access: modify 
mechanism: by reference 


Value identifying the data stream that DCX$ANALYZE DONE deletes. 

The context argument is the address of a longword containing this value. 
DCX$ANALY ZE_INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneous! y. 


Condition Values Returned 


DCX$ INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


DCX$ NORMAL Normal successful completion. 
This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$ANALYZE_INIT 


DCX$ANALYZE_INIT—Initialize Analysis Context 


Format 


Returns 


Arguments 


The DCX$ANALY ZE_INIT routine initializes the context area for a statistical 
analysis of the data records to be compressed. 


DCX$ANALYZE_INIT context [,item_code ,item_value] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$ANALYZE_INIT initializes. 

The context argument is the address of a longword containing this value. 
DCX$ANALY ZE_INIT writes this context into the context argument; you should 
not modify its value. You can define multiple context arguments to identify 
multiple data streams that are processed simultaneously. 


item_code 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item code specifying information that you want DCX$ANALYZE_INIT to use 
in its analysis of data records and in its computation of the mapping function. 
DCX$ANALY ZE_INIT reads this item_code argument, which is the address of 
the longword contained in the item code. 


For each item_code argument specified in the call, you must also specify a 
corresponding item_value argument. The item_value argument contains the 
interpretation of the item_code argument. 


The following symbolic names are the five legal values of the item_code 
argument: 


DCX$C_BOUNDED 
DCX$C_EST_BYTES 
DCX$C_EST_RECORDS 
DCX$C_LIST 
DCX$C_ONE_PASS 
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item_value 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value of the corresponding item_code argument. DCX$ANALY ZE_INIT reads 
the item_value argument, which is the address of a longword containing the 
item value. 


The item_code and item_value arguments always occur as a pair, and together 
they specify one piece of “advice” for the DCX routines to use in computing the 
map function. Note that, unless stated otherwise in the list of item codes and 
item values, no piece of “advice” is binding on DCX; that is, DCX is free to follow 
or not to follow the “advice.” 


The following table shows, for each item_code argument, the possible values for 
the corresponding item_value argument: 


Item Code Corresponding Item Value 


DCX$C_BOUNDED A Boolean variable. If bit <O>is true (equals 1), 
you are stating your intention to submit for analysis 
all data records that will be compressed; doing so 
often enables DCX to compute a better compression 
algorithm. If bit <O>is false (equals 0) or if the 
DCX$C_BOUNDED item code is not specified, DCX 
computes a compression algorithm without regard 
for whether all records to be compressed will also be 
submitted for analysis. 


DCX$C_EST_ BYTES A longword value containing your estimate of the 
total number of data bytes that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of bytes 
are presented for analysis. If you do not specify the 
DCX$C_EST_BYTES item code, DCX submits for 
compression the same number of bytes that was 
presented for analysis. Note that you may specify 
DCX$C_EST RECORDS or DCX$C_ EST BYTES, 
or both. 


DCX$C_EST_RECORDS A longword value containing your estimate of the 
total number of data records that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of records 
are presented for analysis. If you do not specify the 
DCX$C_EST RECORDS item code, DCX submits 
for compression the same number of bytes that was 
presented for analysis. 
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DCX$ANALYZE_INIT 


ltem Code 


Corresponding Item Value 


DCX$C_LIST 


DCX$C_ONE_PASS 


Address of an array of 2*n+1 longwords. The 
first longword in the array contains the value 
2*n+1. The remaining longwords are paired; there 
are n pairs. The first member of the pair is an 
item code, and the second member of the pair is 
the address of its corresponding item value. The 
DCX$C_LIST item code allows you to construct an 
array of item-code and item-value pairs and then 
to pass the entire array to DCX$ANALYZE_INIT. 
This is useful when your language has difficulty 
interpreting variable-length argument lists. Note 
that the DCX$C_LIST item code may be specified, 
in a single call, alone or together with any of the 
other item-code and item-value pairs. 


A Boolean variable. If bit <0O>is true (equals 1), you 
make a binding request that DCX make only one 
pass over the data to be analyzed. If bit <O> is false 
(equals 0) or if the DCX$C_ONE_PASS item code is 
not specified, DCX may make multiple passes over 
the data, as required. Typically, DCX makes one 
pass. 


Description 


The DCX$ANALY ZE_INIT routine initializes the context area for a statistical 
analysis of the data records to be compressed. The first (and typically the only) 
argument passed to DCX$ANALYZE_INIT is an integer variable to contain the 
context value. The DCX facility assigns a value to the context variable and 
associates the value with the created work area. Each time you want a record 
analyzed in that area, specify the associated context variable. You can analyze 
two or more files at once by creating a different work area for each file, giving 
each area a different context variable, and analyzing the records of each file in 


the appropriate work area. 


Condition Values Returned 


DCX$ INVITEM 


DCX$ NORMAL 


Error; invalid item code. The number of 
arguments specified in the call was incorrect 
(this number should be odd), or an unknown item 
code was specified. 


Normal successful completion. 


This routine also returns any condition values returned by LIB$GET_VM. 
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DCX$COMPRESS_DATA 


DCX$COMPRESS_DATA—Compress a Data Record 


Format 


Returns 


Arguments 


The DCX$COMPRESS DATA routine compresses a data record. Call this routine 
for each data record to be compressed. 


DCX$COMPRESS DATA context ,in_rec ,out_rec [,out_length] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value identifying the data stream that DCX$COMPRESS DATA compresses. 
The context argument is the address of a longword containing this value. 
DCX$COMPRESS INIT initializes the value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneous! y. 


in_rec 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Data record to be compressed. The in_rec argument is the address of the 
descriptor of the data record string. 


out_rec 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Data record that has been compressed. The out_rec argument is the address of 
the descriptor of the compressed record that DCX$COMPRESS DATA returns. 
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out_length 

OpenVMS usage: word_signed 

type: word integer (signed) 
access: write only 
mechanism: by reference 


Length (in bytes) of the compressed data record. The out_length argument is 
the address of a word into which DCX$COMPRESS DATA returns the length of 
the compressed data record. 


Description 


The DCX$COMPRESS DATA routine compresses a data record. Call this routine 
for each data record to be compressed. As you compress each record, write the 
compressed record to the file containing the compression/expansion map. For 
each record, write the length of the record and substring string containing the 
record to the same file. See the COMPRESS DATA section in Example 7-1. 


Condition Values Returned 


DCX$ INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


DCX$ INVDATA Error. You specified the item value DCX$C_ 
BOUNDED in the DCX$ANALY ZE_INIT routine 
and attempted to compress a data record (using 
DCX$COMPRESS DATA) that was not presented 
for analysis (using DCX$ANALYZE_ DATA). 
Specifying the DCX$C_BOUNDED item value 
means that you must analyze all data records 
that are to be compressed. 

DCX$_ INVMAP Error; invalid map. The map argument was not 
specified correctly in the DCX$ANALY ZE_INIT 
routine or the context area is invalid. 

DCX$ NORMAL Normal successful completion. 

DCX$ TRUNC Error. The compressed data record has been 
truncated because the out_rec descriptor did 
not specify enough memory to accommodate the 
record. 


This routine also returns any condition values returned by LIB$ANALYZE _ 
SDESC_R2 and LIB$SCOPY_R_DxX. 
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DCX$COMPRESS DONE—Specify Compression Complete 


The DCX$COMPRESS DONE routine deletes the context area and sets the 
context variable to zero. 


Format 
DCX$COMPRESS_DONE context 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Argument 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$COMPRESS DONE deletes. 
The context argument is the address of a longword containing this value. 
DCX$COMPRESS INIT writes the value into the context argument; you should 
not modify its value. You can define multiple context arguments to identify 
multiple data streams that are processed simultaneously. 
Description 


The DCX$COMPRESS_DONE routine deletes the context area and sets the 
context variable to zero, undoing the work of the DCX$COMPRESS INIT routine. 
Call DCX$COMPRESS DONE when all data records have been compressed 
(using DCX$COM PRESS DATA). After calling DCX$COMPRESS DONE, call 
LIB$FREE_VM to free the virtual memory that DCX$MAKE_MAP used for the 
compression/expansion function. 


Condition Values Returned 


DCX$ INVCTX Error. The context variable is invalid or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


DCX$ NORMAL Normal successful completion. 


This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$COMPRESS INIT 


DCX$COMPRESS _INIT—Initialize Compression Context 


Format 


Returns 


Arguments 


Description 


The DCX$COMPRESS INIT routine initializes the context area for the 
compression of data records. 


DCX$COMPRESS INIT context ,map 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$COMPRESS INIT initializes. The 
context argument is the address of a longword containing this value. You should 
not modify the context value afters DCX$COMPRESS INIT initializes it. You 
can define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 


map 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


The function created by DCX$MAKE_MAP. The map argument is the address of 
the compression/expansion function's virtual address. 


The map argument must remain at this address until data compression is 
completed and the context is deleted by means of a call to DCX$COMPRESS _ 
DONE. 


The DCX$COMPRESS INIT routine initializes the context area for the 
compression of data records. 


Call the DCX$COMPRESS INIT routine after calling the DCX$ANALYZE DONE 
routine. 
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Condition Values Returned 


DCX$_INVMAP Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 
DCX$ NORMAL Normal successful completion. 


This routine also returns any condition values returned by LIB$GET_VM and 
LIB$FREE_VM. 
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DCX$EXPAND_DATA—Expand a Compressed Data Record 


The DCX$E XPAND_DATA routine expands (or restores) a compressed data record 
to its original state. 


Format 
DCX$EXPAND_DATA context ,in_rec ,out_rec [,out_length] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Value identifying the data stream that DCX$E XPAND_DATA expands. 

The context argument is the address of a longword containing this value. 
DCX$EXPAND _INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 


in_rec 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Data record to be expanded. The in_rec argument is the address of the descriptor 
of the data record string. 


out_rec 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Data record that has been expanded. The out_rec argument is the address of the 
descriptor of the expanded record returned by DCX$E XPAND_DATA. 
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DCX$EXPAND_DATA 


out_length 


OpenVMS usage: word_signed 
word integer (signed) 


type: 
access: 
mechanism: 


Length (in bytes) of the expanded data record. The out_length argument is the 
address of a word into which DCX$E XPAND_DATA returns the length of the 


expanded data record. 


Description 


The DCX$E XPAND_DATA routine expands (or restores) a compressed data record 
to its original state. Call this routine for each data record to be expanded. 


Condition Values Returned 


DCX$ INVCTX 


DCX$ INVDATA 


DCX$_INVMAP 


DCX$ NORMAL 
DCX$ TRUNC 


Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


Error. A compressed data record is invalid 
(probably truncated) and therefore cannot be 
expanded. 

Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 
Normal successful completion. 

Warning. The expanded data record has been 
truncated because the out_rec descriptor did 
not specify enough memory to accommodate the 
record. 


This routine also returns any condition values returned by LIB$ANALY ZE _ 
SDESC_R2 and LIB$SCOPY_R_DX. 
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DCX$EXPAND_DONE—Specify Expansion Complete 


The DCX$EXPAND_DONE routine deletes the context area and sets the context 
variable to zero. 


Format 
DCX$EXPAND_ DONE context 

Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$EXPAND_DONE deletes. The 
context argument is the address of a longword containing this value 
DCX$E XPAND _INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

Description 


The DCX$EXPAND_DONE routine deletes the context area and sets the context 
variable to zero, thus undoing the work of the DCX$E XPAND_INIT routine. 
Call DCX$EXPAND_DONE when all data records have been expanded (using 
DCX$E XPAND_DATA). 


Condition Values Returned 


DCX$ INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


DCX$NORMAL Normal successful completion. 
This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$EXPAND_INIT—Initialize Expansion Context 


The DCX$EXPAND_INIT routine initializes the context area for the expansion of 
data records. 


Format 
DCX$EXPAND_INIT context ,map 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: write only 
mechanism: by reference 
Value identifying the data stream that DCX$EXPAND_INIT initializes. The 
context argument is the address of a longword containing this value. After 
DCX$E XPAND_INIT initializes this context value, you should not modify it. You 
can define multiple context arguments to identify multiple data streams that are 
processed simultaneous! y. 
map 
OpenVMS usage: address 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Compression/expansion function (created by DCX$MAKE_MAP). The map 
argument is the address of the compression/expansion function's virtual address. 
The map argument must remain at this address until data expansion is 
completed and context is deleted by means of a call to DCX$EXPAND_ DONE. 
Description 


The DCX$EXPAND_INIT routine initializes the context area for the expansion of 
data records. 


Call the DCX$E XPAND_INIT routine as the first step in the expansion (or 
restoration) of compressed data records to their original state. 


Before you call DCX$E XPAND _INIT, read the length of the compressed file from 
the compression/expansion function (the map). Invoke LIB$GET_VM to get the 
necessary amount of storage for the function. LIB$GET_VM returns the address 
of the first byte of the storage area. 
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Condition Values Returned 


DCX$_ INVMAP Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 
DCX$ NORMAL Normal successful completion. 


This routine also returns any condition values returned by LIB$GET_VM. 
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DCX$MAKE_MAP—Compute the Compression/Expansion Function 


Format 


Returns 


Arguments 


The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. 


DCX$MAKE_MAP _ context ,map_addr [,map_size] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value identifying the data stream that DCX$MAKE_MAP maps. The context 
argument is the address of a longword containing this value. DCX$ANALY ZE _ 
INIT initializes this value; you should not modify it. You can define multiple 
context arguments to identify multiple data streams that are processed 
simultaneously. 


map_addr 

OpenVMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Starting address of the compression/expansion function. The map_addr 
argument is the address of a longword into which DCX$MAKE_MAP stores 
the virtual address of the compression/expansion function. 


map_size 

OpenVMS usage: longword_signed 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Length of the compression/expansion function. The map_size argument is the 
address of the longword into which DCX$MAKE_MAP writes the length of the 
compression/expansion function. 
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Description 


The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALY ZE_DATA to compute the compression/expansion function. In 
essence, this map is the algorithm used to shorten (or compress) the original data 
records as well as to expand the compressed records to their original form. 


The map must be available in memory when any data compression or 
expansion takes place; the address of the map is passed as an argument to 
the DCX$COMPRESS INIT and DCX$EXPAND_INIT routines, which initialize 
the data compression and expansion procedures, respectively. 


The map is stored with the compressed data records, because the compressed 
data records are indecipherable without the map. When compressed data records 
have been expanded to their original state and no further compression is desired, 
you should delete the map using the LIB$FREE_VM routine. 


DCX requires that you submit data records for analysis and then call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$ AGAIN status code, 

you must again submit data records for analysis (in the same order) and call 
DCX$MAKE_MAP again; on the second iteration, DCX$MAKE_MAP returns the 
DCX$ NORMAL status code. 


Condition Values Returned 


DCX$ AGAIN Informational. The map has not been created 
and the map_addr and map size arguments 
have not been written because further analysis is 
required. The data records must be analyzed 
(using DCX$ANALYZE_ DATA) again, and 
DCX$MAKE_MAP must be called again before 
DCX$MAKE_MAP will create the map and 
return the DCX$ NORMAL status code. 

DCX$ INVCTX Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 


DCX$ NORMAL Normal successful completion. 


This routine also returns any condition values returned by LIB$GET_VM and 
LIB$FREE_VM. 
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DEC Text Processing Utility (DECTPU) 
Routines 


This chapter describes callable DEC Text Processing Utility (DECTPU) routines. 
It describes the purpose of the DECTPU callable routines, the parameters for the 
routine call, and the primary status returns. The parameter in the call syntax 
represents the object that you pass toa DECTPU routine. Each parameter 
description lists the data type and the passing mechanism for the object. The 
data types are standard OpenVMS data types. The passing mechanism indicates 
how the parameter list is interpreted. 


This chapter is written for system programmers who are familiar with the: 
* OpenVMS Calling Standard 
¢ OpenVMS Run-Time Library 


e Precise manner in which data types are represented on a VAX processor or an 
Alpha processor 


e« Method for calling routines written in a language other than the one you are 
using for the main program 


8.1 Introduction to DECTPU Routines 


Callable DECTPU routines make DECTPU accessible from within other 
languages and applications supported by OpenVMS. DECTPU can be called 
from a program written in any language that generates calls using the OpenVMS 
Calling Standard. You can also call DECTPU from OpenVMS utilities, for 
example, the Mail utility. Callable DECTPU lets you perform text-processing 
functions within your program. 


Callable DECTPU consists of a set of callable routines that resides in the 
DECTPU shareable images. You access callable DECTPU by linking against 
the shareable images, which include the callable interface routine names and 
constants. As with the DCL-level DECTPU interface, you can use files for input 
to and output from callable DECTPU. You can also write your own routines for 
processing file input, output, and messages. 


The calling program must ensure that parameters passed to a called procedure, 
in this case DECTPU, are of the type and form that the DECTPU procedure 
accepts. 


The DECTPU routines described in this chapter return condition values 
indicating the routine’s completion status. When comparing a returned condition 
value with a test value, you should use the LIB$MATCH routine from the 
Run-Time Library. Do not test the condition value as if it were a simple integer. 
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8.1.1 Interfaces to Callable DECTPU 


There are two interfaces you can use to access callable DECTPU: the simplified 
callable interface and the full callable interface. 


8.1.1.1 Simplified Callable Interface 
The easiest way to use callable DECTPU is to use the simplified callable interface. 
DECTPU provides two alternative routines in its simplified callable interface. 
These routines in turn call additional routines that do the following: 


e Initialize the editor 

e« Provide the editor with the parameters necessary for its operation 
e Control the editing session 

e Perform error handling 


When using the simplified callable interface, you can use the TPU$TPU routine 
to specify a command line for DECTPU, or you can call the TPU$EDIT routine 
to specify an input file and an output file. TPU$EDIT builds a command string 
that is then passed to the TPU$TPU routine. These two routines are described in 
detail in Section 8.2. 


If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls the simplified callable interface. You must 
do this because the simplified callable interface destroys all parse information 
obtained and stored before the simplified callable interface was called. 


8.1.1.2 Full Callable Interface 


To use the full callable interface, have your program access the main callable 
DECTPU routines directly. These routines do the following: 


e Initialize the editor (TPU$INTIALIZE) 


e Execute DECTPU procedures (TPU$EXECUTE_INIFILE and 
TPU$EXECUTE_COMMAND) 


¢ Give control to the editor (TPU$CONTROL) 
¢ Terminate the editing session (TPU$CLEANUP) 


When using the full callable interface, you must provide values for certain 
parameters. In some cases, the values you supply are actually addresses for 
additional routines. For example, when you call TPU$INITIALIZE, you must 
include the address of a routine that specifies initialization options. Depending 
on your particular application, you might also have to write additional routines. 
For example, you might need to write routines for performing file operations, 
handling errors, and otherwise controlling the editing session. Callable DECTPU 
provides utility routines that can perform some of these tasks for you. These 
utility routines can do the following: 


e Parse the command line and build the item list used for initializing the editor 
¢ Handle file operations 

e Output error messages 

e Handle conditions 


If your application calls the DECwindows version of DECTPU, the application 
can call TPU$INITIALIZE only once. 
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Various topics relating to the full callable interface are discussed in the following 
sections: 


e Section 8.3 begins by briefly describing the interface. However, most of this 
section describes the main callable DECTPU routines (TPU$INITIALIZE, 
TPU$EXECUTE_INIFILE, TRU$CONTROL, TPU$EXECUTE_ COMMAND, 
and TPU$CLEANUP). 


e Section 8.3.2 discusses additional routines that DECTPU provides for use 
with the full callable interface. 


e Section 8.3.3 defines the requirements for routines that you can write for use 
with the full callable interface. 


The full callable interface consists of the main callable DECTPU routines and the 
DECTPU utility routines. 


8.1.2 The DECTPU Shareable Image 


Whether you use the simplified callable interface or the full callable interface, 
you access callable DECTPU by linking against the DECTPU shareable image. 
This image contains the routine names and constants available for use by an 
application. In addition, the shareable image provides the following symbols: 


e TPU$GL_VERSION—The version of the shareable image 
e TPU$GL_UPDATE—The update number of the shareable image 
e TPU$ FACILITY—The DECTPU facility code 
For more information about how to link to the shareable image TPUSHR.EXE, 
refer to the OpenVMS Programming Environment Manual.! 
8.1.3 Passing Parameters to Callable DECTPU Routines 


Parameters are passed to callable DECTPU routines by reference or by descriptor. 
When the parameter is a routine, the parameter is passed by descriptor as a 
bound procedure value (BPV) data type. 


A bound procedure value is a two-longword entity in which the first longword 
contains a procedure value and the second longword is the environment value (see 
the following figure). The environment value is determined in a language-specific 
manner when the original bound procedure value is generated. When the bound 
procedure is called, the calling program loads the second longword into R1. 


Name of your routine 


Environment 


ZK-4046-GE 


8.1.4 Error Handling 


When you use the simplified callable interface, DECTPU establishes its own 
condition handler, TRUS$HANDLER, to handle all errors. When you use the full 
callable interface, there are two ways to handle errors: 


e You can use the DECTPU default condition handler, TPUSHANDLER. 


1 This manual has been archived but is available on the Op{VMS Documentation 
CD-ROM. 
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e You can write your own condition handler to process some of the errors and 
call TRPUSHANDLER to process the rest. 


The default condition handler, TRU$HANDLER, is described in Section 8.7. 
Information about writing your own condition handler can be found in the HP 
OpenVMS Programming Concepts Manual. 


8.1.5 Return Values 


All DECTPU condition codes are declared as universal symbols. Therefore, you 
automatically have access to these symbols when you link your program to the 
shareable image. The condition code values are returned in RO. Return codes 
for DECTPU can be found in the DEC Tett Processing Utility Reference Manual. 
DECTPU return codes and their messages are accessible from the Help/Message 
facility. 


Additional information about condition codes is provided in the descriptions of 
callable DECTPU routines found in subsequent sections. This information is 
provided under the heading Condition Values Returned and indicates the values 
that are returned when the default condition handler is established. 


8.2 Simplified Callable Interface 


The DECTPU simplified callable interface consists of two routines: TPU$TPU 
and TPU$EDIT. These entry points to DECTPU are useful for the following kinds 
of applications: 


e Those able to specify all the editing parameters on a single command line 
e Those that need to specify only an input file and an output file 


If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls the simplified callable interface. You must 
do this because the simplified callable interface destroys all parse information 
obtained and stored before the simplified callable interface was called. 


The following example calls TPU$EDIT to edit text in the file INFILE.DAT and 
writes the result to OUTFILE.DAT. Note that the parameters to TPU$EDIT must 
be passed by descriptor. 
/* 
Sample C program that calls DECTPU. This program uses TPUSEDIT to 
provide the names of the input and output files 
* 
#include descrip 
int return_status; 


static SDESCRIPTOR (input file, "infile.dat") ; 
static SDESCRIPTOR (output_file, "outfile.dat") ; 


main (argc, argv) 
int argc; 
char *argv[]; 


/* 
Call DECTPU to edit text in "infile.dat" and write the result 
to "outfile.dat". Return the condition code from DECTPU as the 
status of this program. 


ay 
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return status = TPUSEDIT (&input_ file, &output_file) ; 
exit (return_status) ; 


The next example performs the same task as the previous example. This time, 
the TPU$TPU entry point is used. TPU$TPU accepts a single argument which is 
a command string starting with the verb TPU. The command string can contain 
all of the qualifiers that are accepted by the EDIT/TPU command. 


/* 
Sample C program that calls DECTPU. This program uses TPUSTPU and 
specifies a command string 

a 

#include descrip 

int return_status; 


static SDESCRIPTOR (command_prefix, "TPU /NOJOURNAL/NOCOMMAND/OUTPUT=") ; 
static SDESCRIPTOR (input file, "infile.dat") ; 

Static SDESCRIPTOR (output file, "outfile.dat") ; 

Static SDESCRIPTOR (space desc, ""); 


char command_line [100]; 
static SDESCRIPTOR (command_desc, command_line) ; 


main (argc, argv) 
int argc; 
char *argv[ 


{ 

/* 
Build the command line for DECTPU. Note that the command verb 
is TPU instead of EDIT/TPU. The string we construct in the 
buffer command_line will be 

"TPU/NOJOURNAL/NOCOMMAND/OUTPUT=outfile.dat infile.dat" 
k 
i 


return status = STRSCONCAT (&command_desc, 
&command_prefix, 
s&output_file, 
&space_desc, 
&input_file) ; 


if (! return_status) 
exit (return_status) ; 
/* 
Now call DECTPU to edit the file 
vy 
return status = TPUSTPU (&command_desc) ; 
exit (return_status) ; 


The following section contains detailed information about the routines in the full 
DECTPU callable interface. If you use the simplified interface, that interface 
calls these routines for you. If you use the full interface, your code calls these 
routines directly. 


8.3 Full Callable Interface 


The DECTPU full callable interface consists of a set of routines that you can use 
to perform the following tasks: 


e Specify initialization parameters 
e Control file input/output 
e Specify commands to be executed by the editor 
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¢ Control how conditions are handled 


When you use the simplified callable interface, these operations are performed 
automatically. The individual DECTPU routines that perform these functions 
can be called from a user-written program and are known as the DECTPU full 
callable interface. This interface has two sets of routines: the main DECTPU 
callable routines and the DECTPU utility routines. These DECTPU routines, as 
well as your own routines that pass parameters to the DECTPU routines, are the 
mechanism that your application uses to control DECTPU. 


The following sections describe the main callable routines, how parameters are 
passed to these routines, the DECTPU utility routines, and the requirements of 
user-written routines. 


8.3.1 Main Callable DECTPU Utility Routines 
The following callable DECTPU routines are described in this chapter: 
¢ TPUS$INITIALIZE 
e TPU$EXECUTE _INIFILE 
e TPU$CONTROL 
e TPUSEXECUTE_ COMMAND 
e TPUS$CLEANUP 


Note 


Before calling any of these routines, you must establish TPU$HANDLER 
or provide your own condition handler. See the routine description of 
TPUS$HANDLER in this chapter and the HP OpenVMS Calling Standard 
for information about establishing a condition handler. 


8.3.2 Other DECTPU Utility Routines 


The full callable interface includes several utility routines for which you can 
provide parameters. Depending on your application, you might be able to use 
these routines rather than write your own routines. These DECTPU utility 
routines and their descriptions follow: 


¢ TPU$CLIPARSE—Parses a command line and builds the item list for 
TPUS$INITIALIZE 


e TPU$PARSEINFO—Parses a command and builds an item list for 
TPUS$INITIALIZE 


e TPU$FILElO—The default file |/O routine 


e TPUSMESSAGE—Writes error messages and strings using the built-in 
procedure MESSAGE 


¢ TPU$HANDLER—The default condition handler 


e TPU$CLOSE TERMINAL—Closes the DECTPU channel to the terminal (and 
its associated mailbox) for the duration of a CALL_USER routine 


e TPUS$SPECIFY_ASYNC ACTION—Specifies an asynchronous event for 
interrupting the TRU$CONTROL routine 
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TPU$TRIGGER_ASYNC_ACTION—Interrupts the TPU$CONTROL routine 
on a specified asynchronous event 


Note that TPU$CLIPARSE and TPU$PARSEINFO destroy the context 
maintained by the CLI$ routines for parsing commands. 


8.3.3 User-Written Routines 


This section defines the requirements for user-written routines. When these 
routines are passed to DECTPU, they must be passed as bound procedure values. 
(See Section 8.1.3 for a description of bound procedure values.) Depending on 
your application, you might have to write one or all of the following routines: 


Routine for initialization callback—This is a routine that TPU$INITIALIZE 
calls to obtain values for initialization parameters. The initialization 
parameters are returned as an item list. 


Routine for file |/O—This is a routine that handles file operations. Instead 
of writing your own file |/O routine, you can use the TPU$FILEIO utility 
routine. DECTPU does not use this routine for journal file operations or for 
operations performed by the built-in procedure SAVE. 


Routine for condition handling—This is a routine that handles error 
conditions. Instead of writing your own condition handler, you can use 
the default condition handler, TPUSHANDLER. 


Routine for the built-in procedure CALL_USER—This is a routine that is 
called by the built-in procedure CALL_USER. You can use this mechanism to 
cause your program to get control during an editing session. 


8.4 Using the DECTPU Routines: Examples 


Example 8-1, Example 8-2, Example 8-3, and Example 8-4 use callable 
DECTPU. These examples are included here for illustrative purposes only; HP 
does not assume responsibility for supporting these examples. 


Example 8-1 Sample VAX BLISS Template for Callable DECTPU 


MODULE file_io example (MAIN = top level, 


BEGIN 


FORWARD ROUTINE 
top level, 
tpu_init, 
tpu_io; 


ADDRESSING MODE (EXTERNAL = GENERAL)) = 


! Main routine of this example 
! Initialize TPU 
! File I/O routine for TPU 


! Declare the stream data structure passed to the file I/O routine 


| 
MACRO 
stream file id 
stream_rat = 
stream_rfm = 
stream file _nm 


= 0, 0, 325.0 33 ! File ID 
6, 0, 8, 0%, ! Record attributes 
7, 0, 8, 0%, ! Record format 
= 8, 0, 0, 0%; ! File name descriptor 


(continued on next page) 
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Example 8-1 (Cont.) Sample VAX BLISS Template for Callable DECTPU 


! Declare the routines that would actually do the 1/0. These must be supplied 


! in another module 

| 

EXTERNAL ROUTINE 
my_10 open, 
my_io close, 
my_io_get_record, 
my_io put_record; 


! Declare the DECTPU routines 


! 

EXTERNAL ROUTINE 
tpu$fileio, 
tpuShandler, 
tpuSinitialize, 
tpuSexecute_inifile, 
tpuSexecute_command, 
tpuScontrol, 
tpu$cleanup; 

! 


! Declare the DECTPU literals 


| 

EXTERNAL LITERAL 
tpu$k_close, 
tpu$k_close delete, 
tpuSk_ open, 
tpuSk get, 
tpusk put, 


tpu$k_access, 
tpu$k_io, 

tpuSk_input, 
tpuSk output, 


tpu$_calluser, 
tpu$ fileio, 
tpuS_outputfile, 
tpuS_sectionfile, 
tpuS_commandfile, 
tpu$ filename, 
tpuS journalfile, 
tpuS options, 


tpu$m_ recover, 
tpuSm_journal, 
tpusm_read, 
tpu$m_command, 
tpu$m_ create, 
tpu$m_section, 
tpuSm_display, 
tpuSm_output, 


tpuSm_reset_terminal, 
tpu$m_kill processes, 
tpusm_delete exith, 
tpuSm_last_time, 


! Mask for values in options bitmask 


Routine to open a file 
Routine to close a file 
Routine to read a record 
Routine to write a record 


DECTPU'’s internal file I/O routine 


DECTPU's condition handler 
Initialize DECTPU 


Execute the initial procedures 


Execute a DECTPU statement 


Let user interact with DECTPU 
Have DECTPU cleanup after itself 


File I/O operation codes 


File access codes 


! Item list entry codes 


! Masks for cleanup bitmask 
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tpuS nofileaccess, ! DECTPU status codes 
tpu$ openin, 

tpu$_inviocode, 

tpus failure, 

tpus _closein, 

tpuS closeout, 

tpus readerr, 

tpuS writeerr, 

tpuS success; 


ROUTINE top level = 


BEGIN 
I+ 
! Main entry point of your program 


! Your_initialization_routine must be declared as a BPV 


LOCAL 
initialize bpv: VECTOR [2], 
status, 
cleanup flags; 
! 
! First establish the condition handler 
! 
ENABLE 
tpuShandler (); 


! 
! Initialize the editing session, passing TPUSINITIALIZE the address of 
! the bound procedure value which defines the routine which DECTPU is 

! to call to return the initialization item list 

! 


initialize bpv [0] = tpu_init; 
initialize bpv [1] = 0; 
tpuSinitialize (initialize bpv); 
! 


! Call DECTPU to execute the contents of the command file, the debug file 


! or the TPUSINIT PROCEDURE from the section file. 
! 


tpuSexecute_inifile(); 
| 


! Let DECTPU take over. 
| 


tpuscontrol () ; 
! 


! Have DECTPU cleanup after itself 
! 


cleanup flags = tpu$m_reset_terminal OR ! Reset the terminal 
tpu$m_kill processes OR ! Delete Subprocesses 
tpuSm_delete exith OR ! Delete the exit handler 
tpu$m_last_time; ! Last time calling the editor 


tpuscleanup (cleanup flags) ; 
RETURN tpu$ success; 
END; 
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ROUTINE tpu_init = 
BEGIN 


Allocate the storage block needed to pass the file I/O routine as a 


options 


OWN 


file io bpv: VECTOR [2, LONG] 
INITIAL (TPU_IO, 0), 


options; 

| 

! These macros 

| 

MACRO 
out_file = 
com file = 
sec file = 
inp file = 


a zero 


item_list 
WORD 
WORD 
LONG 
LONG 


WORD 
WORD 
LONG 
LONG 


WORD 
WORD 
LONG 
LONG 


WORD 
WORD 
LONG 
LONG 


define the file names passed to DECTPU 


‘QUTPUT.TPU’ % , 
"TPUSCOMMAND’ % , 
'TPUSSECTION’ % , 


'FILE.TPU’ 


Q 
oj 


Create the item list to pass to DECTPU. 
two words which specify the size of the item and its code, the address of 
the buffer containing the data, and a longword to receive a result (always 
zero, Since DECTPU does not return any result values in the item list) 


poor cone noone oo 222-22 ----------- + 
| Item Code | Item Length 

poor reer renee fooccoee-------- + 
| Buffer Address | 
ee + 
| Return Address (always 0) | 
foe e none none e oo 222-22 ----------- + 


O'O 


tions) , 


t 


pus fileio 
1 


Oma ke oOo ct FI 


%CHARCOUNT 
tpus output 


0), 
%CHARCOUNT 


UPLIT BYTE ( 


u$ options) , 


out _file)), 


file), 
UPLIT (%ASCII out_file)), 


com file)), 


tpu$_commandfile) , 


UPLIT (SASCII com_file)), 


0), 


! Options bitmask 


! File I/O routine 


! Output file 


! Command file 
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! 
! 
! bound procedure variable as well as the bitmask for the initialization 
! 
! 


Each item list entry consists of 


Remember that the item list is always terminated with a longword containing 
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WORD (%CHARCOUNT (sec file)), ! Section file 
WORD (tpu$ sectionfile), 


LONG (0), 


LONG (0), 
LONG (0)) 


! Initialize the 
! 


options = tpu$m_display OR 
tpu$m_section OR 
tpu$m_create OR 


tpuSm_command OR 
tpusm_output; 


LONG (UPLIT (%ASCII sec _file)), 


WORD (%SCHARCOUNT (inp file)), ! Input file 
WORD (tpu$ filename) , 
LONG (UPLIT (%ASCII inp file)), 


, ! Terminating longword of 0 
options bitmask 


We have a display 

We have a section file 

Create a new file if one does not 
exist 

We have a section file 

We supplied an output file spec 


! Return the item list as the value of this routine for DECTPU to interpret 


! 
RETURN item list; 


END; 


! End of routine tpu_init 


ROUTINE tpu_io (p opcode, stream: REF BLOCK [ ,byte], data) = 
| 


! This routine determines how to process a TPU I/O request 


BEGIN 


LOCAL 
status; 


Is this one of ours, or do we pass it to TPU’s file I/O routines? 


IF (..p opcode NEQ tpuSk open) AND (.stream [stream_file id] GTR 511) 


THEN 


RETURN tpu$fileio (.p opcode, .stream, .data); 


Either we're opening the file, or we know it’s one of ours 
Call the appropriate routine (not shown in this example) 


SELECTONE ..p opcode OF 


SET 


tpuSk open] : 
status = 


tpuSk_ close, 
status = 


tpuSk_ get]: 
status = 


tpuSk_ put]: 
status = 


OTHERWISE] : 
status = 


TES; 


y_io open (.stream, .data) ; 


tpuSk close delete]: 
y_io close (.stream, .data) ; 


y_io get_record (.stream, .data) ; 


y_io put_record (.stream, .data) ; 


tpu$ failure; 
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RETURN .status; 
END; 

END 

ELUDOM 


! End of routine TPU_IO 


! End Module file _io example 


Example 8-2 shows normal DECTPU setup in HP Fortran. 


Example 8-2 Normal DECTPU Setup in HP Fortran 


c A sample Fortran program that calls DECTPU to act 
C normally, using the programmable interface. 
C 
C IMPLICIT NONE 
INTEGER* 4 CLEAN OPT foptions for clean up routine 
INTEGER* 4 STATUS !return status from DECTPU routines 
INTEGER* 4 BPV_PARSE (2) !set up a bound procedure value 
INTEGER*4 LOC_PARSE !a local function call 
C declare the DECTPU functions 
INTEGER* 4 TPUSCONTROL 
INTEGER* 4 TPUSCLEANUP 
INTEGER* 4 TPUSEXECUTE INIFILE 
INTEGER* 4 TPUSINITIALIZE 
INTEGER* 4 TPUSCLIPARSE 
€ declare a local copy to hold the values of DECTPU cleanup variables 
INTEGER* 4 RESET TERMINAL 
INTEGER* 4 DELETE JOURNAL 
INTEGER* 4 DELETE BUFFERS,DELETE WINDOWS 
INTEGER* 4 DELETE EXITH, EXECUTE PROC 
INTEGER* 4 PRUNE CACHE, KILL PROCESSES 
INTEGER* 4 CLOSE SECTION 
c declare the DECTPU functions used as external 
EXTERNAL TPUSHANDLER 
EXTERNAL TPUSCLIPARSE 
EXTERNAL TPUS$_ SUCCESS ‘external error message 
EXTERNAL LOC_PARSE ‘user supplied routine to 
c call TPUCLIPARSE and setup 
c declare the DECTPU cleanup variables as external these are the 
Cc external literals that hold the value of the options 
EXTERNAL TPUSM_RESET TERMINAL 
EXTERNAL TPUSM DELETE JOURNAL 
EXTERNAL TPUSM DELETE BUFFERS, TPUSM DELETE WINDOWS 
EXTERNAL TPUSM DELETE EXITH, TPUSM_ EXECUTE PROC 
EXTERNAL TPUSM_PRUNE_CACHE,TPUSM KILL PROCESSES 
100 CALL LIBSESTABLISH ( TPUSHANDLER ) testablish the condition handler 
C set up the bound procedure value for the call to TPUSINITIALIZE 
BPV_PARSE( 1 ) = sLOC( LOC PARSE ) 
BPV_PARSE( 2 ) = 0 
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Cc 


AAAR 


AA 


9999 


call the DECTPU initialization routine to do some set up work 
STATUS = TPUSINITIALIZE ( BPV PARSE ) 


Check the status if it is not a success then signal the error 


IF ( STATUS .NE. %LOC ( TPUS SUCCESS ) ) THEN 
CALL LIBSSIGNAL( SVAL( STATUS ) ) 
GOTO 9999 

ENDIF 


execute the TPUS init files and also a command file if it 


was specified in the command line call to DECTPU 

STATUS = TPUSEXECUTE INIFILE ) 

IF ( STATUS .NE. %LOC ( TPUS SUCCESS ) ) THEN !make sure everything is ok 
CALL LIBSSIGNAL( %VAL( STATUS ) ) 
GOTO 9999 

ENDIF 

invoke the editor as it normally would appear 

STATUS = TPUSCONTROL ( ) !call the DECTPU editor 

IF ( STATUS .NE. %LOC ( TPUS SUCCESS ) ) THEN !make sure everything is ok 
CALL LIBSSIGNAL( %VAL( STATUS ) ) 
GOTO 9999 

ENDIF 


Get the value of the option from the external literals. In Fortran you 


cannot use external literals directly so you must first get the value 
of the literal from its external location. Here we are getting the 
values of the options that we want to use in the call to TPUSCLEANUP. 
DELETE JOURNAL = %LOC ( TPUSM DELETE JOURNAL ) 

DELETE EXITH = SLOC ( TPUSM DELETE EXITH ) 

DELETE BUFFERS = %LOC ( TPUSM DELETE BUFFERS ) 

DELETE WINDOWS = %LOC ( TPUSM DELETE WINDOWS ) 

EXECUTE PROC = SLOC ( TPUSM EXECUTE PROC ) 

RESET TERMINAL = %LOC ( TPUSM RESET TERMINAL ) 

KILL PROCESSES = %LOC ( TPUSM KILL PROCESSES ) 

CLOSE SECTION = %LOC ( TPUSM CLOSE SECTION ) 

Now that we have the local copies of the variables we can do the 


logical OR to set the multiple options that we need. 
CLEAN OPT = DELETE JOURNAL .OR. DELETE EXITH .OR. 


1 DELETE BUFFERS .OR. DELETE WINDOWS .OR. EXECUTE PROC 
1 -OR. RESET TERMINAL .OR. KILL PROCESSES .OR. CLOSE SECTION 


do the necessary clean up 
TPUSCLEANUP wants the address of the flags as the parameter so 
pass the *LOC of CLEAN OPT which is the address of the variable 


STATUS = TPUSCLEANUP ( %LOC ( CLEAN OPT ) ) 
IF ( STATUS .NE. %LOC (TPU$ SUCCESS) ) THEN 
CALL LIBSSIGNAL( %VAL(STATUS) ) 


ENDIF 
CALL LIBSREVERT !go back to normal processing -- handlers 


STOP 
END 
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Cc 
C 
INTEGER*4 FUNCTION LOC PARSE 
INTEGER*4 BPV (2) !A local bound procedure value 
CHARACTER* 12 EDIT COMM !A command line to send to TPUSCLIPARSE 
C Declare the DECTPU functions used 
INTEGER*4 TPUSFILEIO 
INTEGER*4 TPUSCLIPARSE 
€ Declare this routine as external because it is never called directly and 
C we need to tell Fortran that it is a function and not a variable 
EXTERNAL TPUSFILEIO 
BPV(1) = %LOC(TPUSFILEIO) !set up the bound procedure value 
BPV(2) = 0 
EDIT COMM(1:12) = ‘TPU TEST.TXT’ 
C parse the command line and build the item list for TPUSINITIALIZE 
9999 LOC_ PARSE = TPUSCLIPARSE (EDIT COMM, BPV , 0) 
RETURN 
END 


Example 8-3 shows how to build a callback item list with HP Fortran. 


Example 8-3 Building a Callback Item List with HP Fortran 


PROGRAM TEST TPU 


C 
IMPLICIT NONE 
Cc 
C Define the expected DECTPU return statuses 
C 
EXTERNAL TPUS_ SUCCESS 
EXTERNAL TPUS_ QUITTING 
EXTERNAL TPUS EXITING 
C 
C Declare the DECTPU routines and symbols used 
Cc 
EXTERNAL TPUSM_DELETE CONTEXT 
EXTERNAL TPUSHANDLER 
INTEGER* 4 TPUSM DELETE CONTEXT 
INTEGER* 4 TPUSINITIALIZE 
INTEGER* 4 TPUSEXECUTE INIFILE 
INTEGER* 4 TPUSCONTROL 
INTEGER* 4 TPUSCLEANUP 
C 
Cc Use LIBSMATCH COND to compare condition codes 
C 
INTEGER* 4 LIBSMATCH_COND 
C 
C Declare the external callback routine 
Cc 
EXTERNAL TPU_STARTUP ! the DECTPU set-up function 
INTEGER* 4 TPU_STARTUP 
INTEGER* 4 BPV (2) ! Set up a bound procedure value 
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C 
Cc Declare the functions used for working with the condition handler 
Cc 
INTEGER*4 LIBSESTABLISH 
INTEGER*4 LIBSREVERT 
C 
C Local Flags and Indices 
C 
INTEGER*4 CLEANUP FLAG ! flag(s) for DECTPU cleanup 
INTEGER*4 RET STATUS 
INTEGER*4 MATCH STATUS 
C 
Cc Initializations 
C 
RET STATUS = 0 
CLEANUP FLAG = SLOC(TPUSM DELETE CONTEXT) 
C 
C Establish the default DECTPU condition handler 
Cc 
CALL LIBSESTABLISH (%REF (TPUSHANDLER) ) 
Cc 
C Set up the bound procedure value for the initialization callback 
C 
BPV(1) = %LOC (TPU STARTUP) 
BPV(2) = 0 
C 
Cc Call the DECTPU procedure for initialization 
Cc 
RET STATUS = TPUSINITIALIZE (BPV) 
IF (RET STATUS .NE. %LOC(TPUS SUCCESS) ) THEN 
CALL LIBSSIGNAL (%VAL(RET STATUS) ) 
ENDIF 
C 
C Execute the DECTPU initialization file 
C 
RET STATUS = TPUSEXECUTE INIFILE() 
IF (RET STATUS .NE. SLOC(TPUS SUCCESS) ) THEN 
CALL LIBSSIGNAL (VAL (RET STATUS) ) 
ENDIF 
Cc 
C Pass control to DECTPU 
C 
RET STATUS = TPUSCONTROL () 
Cc 
C Test for valid exit condition codes. You must use LIBSMATCH COND 
C because the severity of TPU$ QUITTING can be set by the TPU 
6 application 
C 


MATCH STATUS = LIBSMATCH COND (RET STATUS, %LOC (TPUS$ QUITTING) , 
1 SLOC (TPUS EXITING) ) 
IF (MATCH STATUS .EQ. 0) THEN 

CALL LIBSSIGNAL (%VAL (RET STATUS) ) 

ENDIF 
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Cc 
C 
C 


aa 


COQ 


CO e 


HALO 


eonene} AAA 


Oe 


Clean up after processing 


RET STATUS = TPUSCLEANUP (%REF (CLEANUP FLAG) ) 


IF (RET STATUS .NE. %LOC(TPUS SUCCESS) ) THEN 
CALL LIBSSIGNAL (%VAL(RET STATUS) ) 
ENDIF 


Set the condition handler back to the default 


RET STATUS = LIBSREVERT () 
END 


INTEGER*4 FUNCTION TPU_ STARTUP 
IMPLICIT NONE 


INTEGER* 4 OPTION MASK ! temporary variable for DECTPU 
CHARACTER* 44 SECTION NAME ! temporary variable for DECTPU 
External DECTPU routines and symbols 

EXTERNAL TPUSK_ OPTIONS 

EXTERNAL TPUSM_READ 

EXTERNAL TPUSM_SECTION 

EXTERNAL TPUSM_DISPLAY 

EXTERNAL TPUSK_SECTIONFILE 

EXTERNAL TPUSK_ FILEIO 

EXTERNAL TPUSFILEIO 

INTEGER* 4 TPUSFILEIO 

The bound procedure value used for setting up the file I/0 routine 


INTEGER* 4 BPV (2) 


Define the structure of the item list defined for the callback 


STRUCTURE /CALLBACK/ 


INTEGER* 2 BUFFER LENGTH 
INTEGER* 2 ITEM CODE 

INTEGER* 4 BUFFER ADDRESS 
INTEGER* 4 RETURN ADDRESS 


END STRUCTURE 
There are a total of four items in the item list 
RECORD /CALLBACK/ CALLBACK (4) 
Make sure it is not optimized! 
VOLATILE /CALLBACK/ 
Define the options we want to use in the DECTPU session 


OPTION MASK = SLOC(TPUSM SECTION) .OR. %LOC(TPUSM_READ) 
1 .OR. %LOC(TPUSM DISPLAY) 
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C 
C Define the name of the initialization section file 
C 
SECTION NAME = 'TPUSSECTION’ 
C 
Cc Set up the required I/O routine. Use the DECTPU default. 
C 
BPV(1) = *LOC(TPUSFILEIO) 
BPV(2) = 0 
C 
Cc Build the callback item list 
C 
C Set up the edit session options 
C 
CALLBACK (1) . ITEM_CODE - LOC (TPUSK_OPTIONS) 
CALLBACK (1) . BUFFER ADDRESS = LOC (OPTION MASK) 
CALLBACK (1) . BUFFER_LENGTH = 4 
CALLBACK (1) .RETURN_ADDRESS =) 
C 
C Identify the section file to be used 
C 
CALLBACK (2) . ITEM_CODE = SLOC (TPUSK_SECTIONFILE) 
CALLBACK (2) . BUFFER_ADDRESS = LOC (SECTION NAME) 
CALLBACK (2) . BUFFER_LENGTH = LEN (SECTION NAME) 
CALLBACK (2) .RETURN_ ADDRESS = 0 
C 
C Set up the I/O handler 
C 
CALLBACK 3) .ITEM_CODE = LOC (TPUSK_FILEIO) 
CALLBACK 3) .BUFFER_ADDRESS = $LOC(BPV) 
CALLBACK 3) .BUFFER_LENGTH = 4 
CALLBACK 3) .RETURN_ADDRESS =-'0 
C 
C End the item list with zeros to indicate we are finished 
C 
CALLBACK 4) .ITEM_ CODE = 0 
CALLBACK 4) .BUFFER_ ADDRESS = 0 
CALLBACK 4) .BUFFER_ LENGTH =10 
CALLBACK 4) .RETURN_ADDRESS = 0 
Cc 
C Return the address of the item list 
C 
TPU_ STARTUP = %LOC (CALLBACK) 
RETURN 
END 


Example 8-4 shows how to specify a user-written file |/O routine in VAX C. 


Example 8-4 Specifying a User-Written File I/O Routine in VAX C 


/* 

Segment of a simple VAX C program to invoke DECTPU. This program provides its 
own FILEIO routine instead of using the one provided by DECTPU. This program 
will run correctly if you write the routines it calls. 

4 

/* 

** To compile this example use the command: 

$ CC <file-name> 
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** To link this example after a successful compilation: 


$ LINK <file-name>,sys$input/ 
SYSSLIBRARY : VAXCRTL/ SHARE 
<PRESS-Ctrl/Z> 


The TPUSHR shareable image is found by the linker in IMAGELIB.OLB. 
if 

#include descrip 

#include stdio 


/* data structures needed */ 


struct bpv_arg /* bound procedure value */ 
int *routine add ; /* pointer to routine */ 
int env ; /* environment pointer */ 
struct item list_entry /* item list data structure */ 


short int buffer length; /* buffer length */ 


short int item code; /* item code */ 
int *buffer_add; /* buffer address */ 
int *return_len_add; /* return address */ 


a 


struct stream_type 


int ident; /* stream id */ 

short int alloc; /* file size */ 

short int flags; /* file record attributes/format */ 

short int length; /* resultant file name length */ 

short int stuff; /* file name descriptor class & type */ 

int nam_add; /* file name descriptor text pointer */ 
globalvalue tpu$ success; /* TPU Success code */ 
globalvalue tpu$ quitting; /* Exit code defined by TPU */ 
globalvalue /* Cleanup codes defined by TPU */ 


tpu$m_ delete journal, tpu$m delete exith, 
tpu$m_ delete buffers, tpu$m_ delete windows, tpu$m delete cache, 
tpu$m_prune_cache, tpuSm_ execute file, tpu$m_execute_proc, 
tpu$m_ delete context, tpu$m_reset_terminal, tpu$m_kill processes, 
tpu$m_close_ section, tpu$m_delete others, tpuSm_last_time; 
globalvalue /* Item codes for item list entries */ 
tpuSk fileio, tpu$k_options, tpu$k_sectionfile, 
tpuSk commandfile ; 
globalvalue /* Option codes for option item */ 
tpu$m_ display, tpu$Sm_section, tpu$m_command, tpu$m_create ; 


globalvalue /* Possible item codes in item list */ 
tpu$k_access, tpu$k filename, tpu$k defaultfile, 
tpuS$k_relatedfile, tpuSk_ record attr, tpu$k_ maximize ver, 
tpuSk flush, tpu$k filesize; 


globalvalue /* Possible access types for tpuSk_access */ 
tpuSk_ io, tpu$k_input, tpu$k_output; 

globalvalue /* OpenVMS RMS File Not Found message code */ 
rms$_fnf; 
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globalvalue 
tpuSk open, tpuSk close, tpuSk close delete, 
tpuSk get, tpu$k_put; 

int libSestablish (); /* RTL 

int tpuScleanup (); /* TPU 

int tpu$control (); /* TPU 

int tpuSexecute inifile (); 7* TRU 

int tpu$handler (); pete 

int tpu$initialize (); /* TPU 

/* 


| 


/* FILEIO routine functions */ 


routine to establish an event handler */ 
routine to free resources used */ 

routine to invoke the editor */ 

routine to execute initialization code */ 
signal handling routine */ 

routine to initialize the editor */ 


This function opens a file for either read or write access, based upon 
the itemlist passed as the data parameter. Note that a full implementation 
of the file open routine would have to handle the default file, related 
file, record attribute, maximize version, flush and file size item code 


prope 


rly. 


open file (data, stream) 


int 


{ 


*data; 
struct stream type *stream; 


struct item_list_entry *item; 
char *access; /* File access type */ 
char filename[256] ; /* Max file specification size */ 
FILE *fopen() ; 
/* Process the item list */ 
item = data; 
while (item->item_code != 0 && item->buffer length != 0) 
if (item->item_code == tpu$k_ access) 
if (item->buffer_add == tpu$k_io) access = "r+"; 
else if (item->buffer_add == tpu$k_input) access = "r"; 


else if (item->buffer_ add 


} 


== tpuSk output) access = "w"; 


else if (item->item_code == tpu$k_filename) 


strncpy (filename, item->buffer_add, item->buffer length) ; 
filename [item->buffer length] = 0; 
libSscopy_r dx (&item->buffer length, item->buffer add, 


&stream->length) ; 


/* to be flushed to disk as written */ 


else if (item->item_code == tpu$k_defaultfile) 
/* Add code to handle default file */ 

} /* spec here */ 
else if (item->item_code == tpu$k_relatedfile) 

{ /* Add code to handle related */ 

} /* file spec here */ 
else if (item->item_code == tpuSk record attr) 

{ /* Add code to handle record */ 

} /* attributes for creating files */ 
else if (item->item_code == tpu$k_maximize ver) 

{ /* Add code to maximize version */ 

} /* number with existing file here */ 
else if (item->item_code == tpu$k_flush) 

/* Add code to cause each record */ 
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else if (item->item_code == tpu$k_ filesize) 
/* Bdd code to handle specification */ 
} /* of initial file allocation here */ 
++item; /* get next item */ 


stream->ident = fopen(filename, access) ; 
if (stream->ident != 0) 
return tpu$ success; 
else 
return rms$_fnf; 
/* 
This procedure closes a file 
at 
close file (data, stream) 
struct stream _type *stream; 


close (stream->ident) ; 
return tpu$ success; 


/* 
This procedure reads a line from a file 
oy) 

read_line (data, stream) 

struct dsc$descriptor *data; 

struct stream_type *stream; 


{ 


char textline [984]; /* max line size for TPU records */ 
int len; 
globalvalue rms$_ eof; /* RMS End-Of-File code */ 
if (fgets (textline,984,stream->ident) == NULL) 
return rms$_ eof; 
else 


{ 


len = strlen(textline) ; 
if (len > 0) 
len = len - 1; 
return libSscopy r dx (&len, textline, data) ; 


/* 
This procedure writes a line to a file 
we 

write line (data, stream) 

struct dsc$descriptor *data; 

struct stream_type *stream; 


{ 


char textline [984]; /* max line size for TPU records */ 


strncpy (textline, data->dsc$a_pointer, data->dsc$w_length) ; 
textline [data->dsc$w length] = 0; 

fputs(textline, stream->ident) ; 

fputs("\n", stream->ident) ; 

return tpu$ success; 


(continued on next page) 
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Example 8-4 (Cont.) Specifying a User-Writien File I/O Routine in VAX C 


/* 
This procedure will handle 1/0 for TPU 
*/ 
fileio(code, stream, data) 
int *code; 
int *stream; 
int *data; 
ts 
int status; 
/* Dispatch based on code type. Note that a full implementation of the */ 
/* file I/O routines would have to handle the close and delete code properly */ 
/* instead of simply closing the file */ 
if (*code == tpuS$k_open) /* Initial access to file */ 
status = open file (data,stream) ; 
else if (*code == tpu$k close) /* End access to file */ 
status = close file (data, stream) ; 
else if (*code == tpu$k close delete) /* Treat same as close */ 
status = close file (data,stream) ; 
else if (*code == tpu$k_get) /* Read a record from a file */ 
status = read_line (data,stream) ; 
else if (*code == tpu$k_put) /* Write a record to a file */ 
status = write line (data,stream) ; 
else 
{ /* Who knows what we have? */ 
status = tpu$ success; 
printf ("Bad FILEIO I/O function requested") ; 
return status; 
} 
/* 
This procedure formats the initialization item list and returns it as 
its return value. 
*/ 
callrout () 


static struct bpv_arg add block = 

fileio, 0 } ; ~  /* BPV for fileio routine */ 
int options ; 

char *section_name = "TPUSSECTION"; 

static struct item _list_entry arg[] = 


/* length code buffer add return add */ 
4,tpusk fileio, 0, 0}, 
4,tpuSk options, 0, 0}, 
0,tpusk_sectionfile,0, 0 | 
0,0, 0, 0 


te 
/* Setup file I/O routine item entry */ 
arg[0].buffer_add = &add_block; 


/* Setup options item entry. Leave journaling off. */ 
options = tpu$m display | tpu$m_ section; 
arg[1] .buffer_add = &options; 


/* Setup section file name */ 


arg[2].buffer length = strlen(section name) ; 
arg[2].buffer_add = section_name; 
return arg; 


(continued on next page) 
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Example 8-4 (Cont.) Specifying a User-Written File l/O Routine in VAX C 


/* 
Main program. Initializes TPU, then passes control to it. 
Fi 
main () 


{ 


int return_status ; 
int cleanup options; 
struct bpv_arg add_block; 


/* Establish as condition handler the normal DECTPU handler */ 
libSestablish(tpu$handler) ; 
/* Setup a BPV to point to the callback routine */ 


add_block.routine_add = callrout ; 
add_block.env = 0; 


/* Do the initialize of DECTPU */ 


return status = tpu$initialize(&add_block) ; 
if (!return_status) 
exit (return_status) ; 


/* Have TPU execute the procedure TPUSINIT PROCEDURE from the section file */ 
/* and then compile and execute the code from the command file */ 


return status = tpuSexecute_inifile()j; 
if (!return_status) 
exit (return_status) ; 


/* Turn control over to DECTPU */ 


return_status = tpuScontrol (); 
if (!return_status) 
exit (return_status) ; 


/* Now clean up. */ 


cleanup options = tpu$m_last time | tpu$m delete context; 
return_status = tpuS$cleanup (&cleanup options) ; 
exit (return_status) ; 


printf ("Experiment complete") ; 


8.5 Creating and Calling a USER Routine 


This section describes the steps involved in creating an executable image for the 
USER routine and how to call the routine from a C program in the DECTPU 
environment. The following list describes the steps in creating the executable 
image: 


1. Write a program in the appropriate high-level language; in the supporting 
example, the language is C. The program must contain a global routine 
named TPU$CALLUSER. 


Compile the program. 
Link the program with an options file to create a shareable image. 


Define the logical name TPU$CALLUSER to point to the file containing the 
USER routine. 


5. Invoke DECTPU. 
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6. From within a DECTPU session, call the high-level program to perform 
its function by specifying the built-in procedure CALL_USER with the 
appropriate parameters. The built-in procedure passes the specified 
parameters to the appropriate routine. 


8.5.1 The CALL_USER Code 


This is an example of a USER routine written in the VAX C programming 
language. The comments in the code explain the various routine functions. 


/* call user.c */ 

if 7 

A sample of a TPU CALL USER routine written in VAX C. 

The routine is compiled and linked as a shareable image and then the 
DCL logical TPUSCALLUSER is defined to point at the image. 


From within TPU, when the built-in CALL USER is called, this image 
will be activated and the tpu$call_user routine will be called. 


This example is for VAX C but can be updated to work with DEC C with little 
effort. 

ae 

#include <descrip.h> 


extern int lib$sget1_dd(), 
vaxc$crtl init (); 


globalvalue 
tpusS success; 


/* 
Because we know we are being called from a non-C based routine, call 
the CRTL initialization routine once 

*/ 

static int 
rtl_inited = 0; 


extern int tpuScalluser ( 
int *int_ param, 
struct dscSdescriptor *str_param, 
struct dscSdescriptor *result_param ) 
/* 
A sample TPU CALL USER routine that checks access to the file specified 
in the str_ param descriptor. 


Return (in result_param) : 
ACCESS - specified access is allowed 
NOACCESS - specified access is not allowed 
ERROR - Either invalid param or the file does not exist 
PARAM ERROR - Invalid param passed 
MEMORY ERROR - An error occured allocating memory 


An example from TPU code would be: 


file access := CALL USER (0, "SYSSLOGIN:LOGIN.COM") ; 
| 


! Only look at the return value of ACCESS, 
i] 
IF file_access = "ACCESS" 
THEN 

file exists := 1; 
ELSE 

file exists : 
ENDIF; 


0; 
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See the description of the CALL USER built-in for more information on how to 
use the built-in. 


Wy 


{ 

static char 
*error str = "ERROR", 
*param_error_str = "PARAM ERROR", 
*memory error _str = "MEMORY ERROR", 
*access str = "ACCESS", 
*noaccess str = "NOACCESS"; 

char 
*result_str_ptr; 

int 
result_str_length; 

/* 
If this is the first time in, call the VAXCRTL routine to init things 

* 

/ 

if (rtl_inited == 0) { 
vaxc$crtl init(); 
rtl inited = 1; 


/* 
The integer must be between 0 and 7 for the 
call to the C RTL routine ACCESS 

Ws 
if ((*int_param < 0) || (*int_param > 7)) { 
result_str_length = strlen (param_error str) ; 
result_str_ptr = param_error str; 


else { 
/* 
If we were passed a null string, 
set the param_error return value 
ae 


if (str_param->dsc$w_ length == 0) { 

result_str_ length = strlen (param_error str) ; 

result_str_ptr = param error str; 
else { 

/* 

Because there is NO way of knowing if the descriptor we have 

been passed ends with a \0, we need to create a valid string 
pass to the rtl routine "access" 


Allocate memory enough for the string plus the null character 
ty 
str_ptr = (char *) malloc (str_param->dsc$w_length + 1); 
/* 

Make sure the memory allocation worked... 
ie 
if (str_ptr == 0) { 

result_str_ length = strlen (memory_error str) ; 

result_str_ptr = memory error str; 
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else { 

/* 
Move the bytes from the descriptor into the memory 
pointed to by str ptr, and end it with a \0 
Then call the access routine, free the memory 

* 

/ 

sprintf (str_ptr, "%.*s\0", str _param->dsc$w length, 

str_param->dsc$a_pointer) ; 

if (access (str_ptr, *int_param) == 0) { 
result_str_length = strlen (access str) ; 
result_str_ptr = access str; 


else { 
result_str_ length = strlen (noaccess str) ; 
result_str_ptr = noaccess str; 


free (str ptr) ; 


} 


/* Setup the return descriptor */ 
libS$sget1l_dd (&result_str_length, result_param) ; 
k 


Copy the result bytes into the descriptor’s dynamic 
memory 
ay 
memcpy (result _param->dsc$a_ pointer, result_str ptr, 
result_str length) ; 


return tpuS_success; 


Use the following command to compile the routine with the VAX C compiler: 


$ CC/LIST call_user.c 


8.5.2 Linking the CALL_USER Image 


To link the CALL_USER image as a shareable image requires a linker option file 
similar to the one that follows: 


! CALL USER.OPT 
call_user.obj 
UNIVERSAL=TPUSCALLUSER 
SYSSLIBRARY : VAXCRTL/SHARE 


After you create the linker option file, use the following command to link the 
shareable image: 


$ LINK CALL _USER/OPT/SHARE/MAP/FULL 
This command produces a shareable image named CALL_USER.EXE. 


The description of the DECTPU built-in CALL_USER states that you must define 
the logical name TPU$CALLUSER to point to the image that contains the USER 
procedure. Use the following command to define the logical name: 


$ DEFINE TPUSCALLUSER SYSSDISK: [] CALL_USER.EXE 


If you move the image to another device and directory, you must appropriately 
revise the pointer. 


DEC Text Processing Utility (DECTPU) Routines DECTPU-25 


DEC Text Processing Utility (DECTPU) Routines 
8.6 Accessing the USER Routine from DECTPU 


8.6 Accessing the USER Routine from DECTPU 


To access the USER routine from DECTPU, your code must call the CALL_USER 
built-in procedure. The CALL_USER built-in procedure activates the shareable 
image pointed to by the logical name TPU$CALLUSER and calls the USER 
routine within that image. The following is an example of DECTPU code that can 
be used with the USER example routine in Section 8.5.1. 


Module: CALL USER.TPU - the access routine 


! 
! 
! Constants used with the call to this procedure (or directly to the call_user 
! 
| 


routine) . 
CONSTANT 
ACCESS FILE EXISTS := 0, 
ACCESS FILE EXECUTE := 1, 
ACCESS FILE WRITE := 2, 
ACCESS FILE DELETE := 2, 
ACCESS FILE READ := 4, 
ACCESS FILE EXE DEL := ACCESS FILE EXECUTE + ACCESS FILE DELETE, 
ACCESS FILE EXE WRITE := ACCESS FILE EXE DEL, 
ACCESS FILE DEL READ := ACCESS FILE DELETE + ACCESS FILE READ, 
ACCESS FILE DEL WRITE := ACCESS FILE DEL READ, 
ACCESS FILE EXE READ := ACCESS FILE EXECUTE + ACCESS FILE READ; 
PROCEDURE access (val, the file) 


! Call the CRTL function ACCESS via the TPU CALL USER built-in 
! 
! 0 = exists 
! 1 = execute 
2 = write (& delete) 
4 = read 
(add them for combinations) 
! Return Values: 
! 1 = requested access is allowed 
! 0 = requested access is NOT allowed 
! -1 = an error occured with the built-in 
! Side Effects: 


A message may end up in the message buffer if there is an error 


! 
LOCAL 

ret_val; 
! Handle the call _user errors 
ON ERROR 
TPUS_BADUSERDESC] 
MESSAGE (ERROR_TEXT) ; 
RETURN -1; 
TPUS NOCALLUSER] : 
MESSAGE ("Could not find access call_user routine - check logicals") ; 
RETURN -1; 
TPUS_CALLUSERFAIL] 
MESSAGE ("Something is wrong in the access call user routine") ; 
MESSAGE (ERROR_TEXT) ; 
RETURN -1 
OTHERWISE] 
MESSAGE (ERROR_TEXT) ; 
ETURN -1; 
DON ERROR; 


2a 


E 
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ret_val := CALL USER (val, the file); 
CASE ret_val 

["ACCESS"] 

RETURN 1; 

["NOACCESS"] 

RETURN 0; 

[OUTRANGE] Gi 

MESSAGE ("Error with call to access routine: " + ret_val); 
ENDCASE; 

RETURN -1; 

ENDPROCEDURE; 


You can extend the EVE editor using the DECTPU code described at the 
beginning of this section. Copy the code to a file named CALL_USER.TPU in the 
current working directory and then execute the following commands: 


GET FILE CALL_USER.TPU 
EXTEND ALL 


To use the DECTPU routine ACCESS from EVE, write a DECTPU procedure 
EVE_EXISTS, coded as follows: 


PROCEDURE eve exists (the file) 
IF access (ACCESS FILE EXISTS, the file) = 1 


THEN 

MESSAGE ("File " + the file + " exists"); 
ELSE 

MESSAGE ("No such file " + the file ); 
ENDIF; 
ENDPROCEDURE ; 


This enables calls from the command line such as: 
Command: exists sys$login:login.com 


This command directs that the message window indicate whether the file 
SYS$LOGIN:LOGIN.COM exists. 


8.7 DECTPU Routines 
This section describes the individual DECTPU routines. 
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TPU$SCLEANUP—Free System Resources Used During DECTPU 


Format 


Returns 


Argument 


Session 


The TPU$CLEANUP routine cleans up internal data structures, frees memory, 
and restores terminals to their initial state. 


This is the final routine called in each interaction with DECTPU. 


TPU$CLEANUP flags 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or mask) defining the cleanup options. The flags argument is the address 
of a longword bit mask defining the cleanup options or the address of a 32-bit 
mask defining the cleanup options. This mask is the logical OR of the flag bits 
you want to set. Following are the various cleanup options: 


Flag! Function 
TPU$M_ DELETE _J OURNAL Closes and deletes the journal file if it is open. 
TPU$M_ DELETE EXITH Deletes the DECTPU exit handler. 


TPU$M DELETE BUFFERS Deletes all text buffers. If this is not the 
last time you are calling DECTPU, then all 
variables referring to these data structures 
are reset, as if by the built-in procedure 
DELETE. If a buffer is deleted, then all 
ranges and markers within that buffer, and 
any subprocesses using that buffer, are also 
deleted. 


1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific fidld 
in which the bit is set. TPU$V_ isa bit number. 
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Flag' 


Function 


TPU$M_DELETE_WINDOWS 


TPU$M_DELETE_CACHE 


TPU$M_PRUNE_CACHE 


TPU$M_EXECUTE_FILE 


TPU$M_EXECUTE_PROC 


TPU$M_DELETE_CONTEXT 


TPU$M_RESET_TERMINAL 


TPU$M_KILL_PROCESSES 


Deletes all windows. If this is not the last 
time you are calling DECTPU, then all 
variables referring to these data structures 
are reset, as if by the built-in procedure 
DELETE. 


Deletes the virtual file manager’s data 
structures and caches. If this deletion is 
requested, then all buffers are also deleted. If 
the cache is deleted, the initialization routine 
has to reinitialize the virtual file manager the 
next time it is called. 


Frees up any virtual file manager caches that 
have no pages allocated to buffers. This frees 
up any caches that may have been created 
during the session but are no longer needed. 


Reexecutes the command file if 
TPU$EXECUTE_INIFILE is called again. 
You must set this bit if you plan to specify 

a new file name for the command file. This 
option is used in conjunction with the option 
bit passed to TPU$INITIALIZE indicating the 
presence of the /COMMAND qualifier. 


Looks up TPU$INIT PROCEDURE and 
executes it the next time TPU$EXECUTE _ 
INIFILE is called. 


Deletes the entire context of DECTPU. If this 
option is specified, then all other options are 
implied, except for executing the initialization 
file and initialization procedure. 

Resets the terminal to the state it was in 
upon entry to DECTPU. The terminal mailbox 
and all windows are deleted. If the terminal 
is reset, then it is reinitialized the next time 
TPUSINITIALIZE is called. 


Deletes all subprocesses created during the 
session. 


1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field 
in which the bit is set. TPU$V_ is a bit number. 
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Flag! Function 


TPU$M_CLOSE SECTION2 Closes the section file and releases the 
associated memory. All buffers, windows, 
and processes are deleted. The cache is 
purged and the flags are set for reexecution 
of the initialization file and initialization 
procedure. If the section is closed and if 
the option bit indicates the presence of the 
SECTION qualifier, then the next call to 
TPUS$INITIALIZE attempts a new restore 
operation. 

TPU$M DELETE OTHERS Deletes all miscellaneous preallocated data 
structures. Memory for these data structures 
is reallocated the next time TPU$INITIALIZE 
is called. 

TPU$M_LAST_TIME This bit should be set only when you are 
calling DECTPU for the last time. Note that 
if you set this bit and then recall DECTPU, 
the results are unpredictable. 


1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field 
in which the bit is set. TPU$V_ is a bit number. 


2Using the simplified callable interface does not set TPU$ CLOSE_SECTION. This feature allows you 
to make multiple calls to TPU$TPU without requiring you to open and close the section file on each 
call. 


Description 


The cleanup routine is the final routine called in each interaction with DECTPU. 
It tells DECTPU to clean up its internal data structures and prepare for 
additional invocations. You can control what is reset by this routine by setting or 
clearing the flags described previously. 


When you finish with DECTPU, call this routine to free the memory and restore 
the characteristics of the terminal to their original settings. 


If you intend to exit after calling TPU$CLEANUP, do not delete the data 
structures; the operating system does this automatically. Allowing the operating 
system to delete the structures improves the performance of your program. 


Notes 


1. When you use the simplified interface, DECTPU automatically sets the 
following flags: 


* TPU$V_RESET TERMINAL 

* TPU$V_DELETE_BUFFERS 

* TPU$V_DELETE_J OURNAL 
* TPU$V_DELETE_WINDOWS 
* TPU$V_DELETE_EXITH 
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* TPU$V_EXECUTE_PROC 
e TPU$V_EXECUTE FILE 
e TPU$V_PRUNE CACHE 
* TPU$V_KILL_PROCESSES 
2. If this routine does not return a success status, no other calls to the editor 
should be made. 


Condition Value Returned 


TPU$ SUCCESS Normal successful completion. 
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TPU$CLIPARSE—Parse a Command Line 


The TPU$CLIPARSE routine parses a command line and builds the item list for 
TPUSINITIALIZE. 


Format 

TPU$CLIPARSE - string ,fileio ,call_user 
Returns 

OpenVMS usage: item_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

This routine returns the address of an item list. 
Arguments 

string 

OpenVMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 

Command line. The string argument is the address of a descriptor of a DECTPU 

command. 

fileio 

OpenVMS usage: vector_longword_unsigned 

type: bound procedure value 

access: read only 

mechanism: by descriptor 

File 1/O routine. The fileio argument is the address of a descriptor of a file |/O 

routine. 

call_user 

OpenVMS usage: vector_longword_unsigned 

type: bound procedure value 

access: read only 

mechanism: by descriptor 


Call-user routine. The call_user argument is the address of a descriptor of a 
call-user routine. 
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This routine calls CLI$DCL_PARSE to establish a command table and a 
command to parse. It then calls TPU$PARSEINFO to build an item list for 
TPUSINITIALIZE. 


If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TRU$CLIPARSE. You must do this 
because TPU$CLIPARSE destroys all parse information obtained and stored 
before TPU$CLIPARSE was called. 
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TPU$CLOSE_TERMINAL—Close Channel to Terminal 


The TPU$CLOSE_ TERMINAL routine closes the DECTPU channel to the 


terminal. 
Format 
TPU$CLOSE_TERMINAL 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 
Arguments 
None. 
Description 


This routine is used with the built-in procedure CALL_USER and its associated 
call-user routine to control the DECTPU access to the terminal. When a call-user 
routine invokes TPU$CLOSE_TERMINAL, DECTPU closes its channel to the 
terminal and the channel of the DECTPU associated mailbox. 


When the call-user routine returns control to it, DECTPU automatically reopens 
a channel! to the terminal and redisplays the visible windows. 


A call-user routine can use TPU$CLOSE_ TERMINAL at any point in the 

program and as many times as necessary. If the terminal is already closed to 

DECTPU when TPU$CLOSE_TERMINAL is used, the call is ignored. 
Condition Value Returned 


TPU$ SUCCESS Normal successful completion. 
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TPUSCONTROL—Pass Control to DECTPU 


Format 


Returns 


Argument 


Description 


The TPU$CONTROL routine is the main processing routine of the DECTPU 
editor. It is responsible for reading the text and commands and executing them. 
When you call this routine (after calling TPU$INITIALIZE), control is turned 
over to DECTPU. 


TPU$CONTROL [integer] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


integer 

OpenVMS usage: integer 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Prevents DECTPU from displaying the message “Editing session is not being 
journaled” when the calling program gives control to DECTPU. Specify a true 
(odd) integer to preserve compatibility in future releases. If you omit the 
parameter, DECTPU displays the message if journaling is not enabled. 


This routine controls the editing session. It is responsible for reading the text 
and commands and for executing them. Windows on the screen are updated 

to reflect the edits made. Your program can regain control by interrupting 
DECTPU using the TPU$SPECIFY_ASYNC ACTION routine, together with the 
TPU$TRIGGER_ASYNC_ACTION routine. 


Note 


Control is also returned to your program if an error occurs or when you 
enter either the built-in procedure QUIT or the built-in procedure EXIT. 
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Condition Values Returned 


TPU$ EXITING 


TPU$ NONANSICRT 


TPU$ QUITTING 


TPU$ RECOVERFAIL 


A result of EXIT (when the default condition 
handler is established). 

A result of operation termination — results when 
you call DECTPU with TPU$DISPLAY FILE 

set to nodisplay and you attempt to execute 
screen-oriented commands. 

A result of QUIT (when the default condition 
handler is established). 


A recovery operation was terminated abnormally. 
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TPU$EDIT—Edit a File 


Format 


Returns 


Arguments 


The TPU$EDIT routine builds a command string from its parameters and passes 
it tothe TPU$TPU routine. 


TPUS$EDIT is another entry point to the DECTPU simplified callable interface. 


TPU$EDIT input ,output 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


input 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Input file name. The input argument is the address for a descriptor of a file 
specification. 


output 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Output file name. The output argument is the address for a descriptor of an 
output file specification. It is used with the /OUTPUT command qualifier. 
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Description 


This routine builds a command string and passes it to TPU$TPU. If the length 
of the output descriptor is nonzero, then the OUTPUT qualifier is added to 
the command string. The /OUTPUT qualifier causes a file to be written to the 
specified file even if no modifications are made to the input file. If the QUIT 
built-in procedure is called, it prompts the user as if changes had been made 
to the buffer. This allows applications to check for the existence of the output 
file to see if the editing session was terminated, which is consistent with other 
OpenVMS callable editors. 


If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TPU$E DIT. Your application must do this 
because TPU$EDIT destroys all parse information obtained and stored before 
TPU$EDIT is called. 


Condition Values Returned 


This routine returns the same values as TPU$TPU. 
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TPU$SEXECUTE_COMMAND—Execute One or More DECTPU 


Format 


Returns 


Argument 


Description 


Statements 


The TPU$EXECUTE_ COMMAND routine allows your program to execute 
DECTPU statements. 


TPU$EXECUTE_COMMAND string 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


string 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by value 


DECTPU statement. The string argument is the address of a descriptor of a 
character string denoting one or more DECTPU statements. 


This routine performs the same function as the built-in procedure EXECUTE 
described in the DEC Text Processing Utility Reference Manual. 


Condition Values Returned 


TPU$ SUCCESS Normal successful completion. 

TPU$ EXECUTEFAIL Execution aborted. This could be because of 
execution errors or compilation errors. 

TPU$ EXITING EXIT built-in procedure was invoked. 

TPU$ QUITTING QUIT built-in procedure was invoked. 


DEC Text Processing Utility (DECTPU) Routines DECTPU-39 


DEC Text Processing Utility (DECTPU) Routines 
TPU$SEXECUTE_INIFILE 


TPU$SEXECUTE_INIFILE—Execute Initialization Files 


Format 


Returns 


Arguments 


Description 


The TPU$EXECUTE_INIFILE routine allows you to execute a user-written 
initialization file. 

This routine must be executed after the editor is initialized and before any other 
commands are processed. 


TPU$EXECUTE_INIFILE 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


None. 


Calling the TPU$EXECUTE_INIFILE routine causes DECTPU to perform the 
following steps: 


1. The command file is read into a buffer. The default is TPUS$COMMAND.TPU. 
If you specified a file on the command line that cannot be found, an error 
message is displayed and the routine is aborted. 


2. If you specified the /DEBUG qualifier on the command line, the DEBUG file 
is read into a buffer. The default is SYS$SHARE:TPU$DEBUG.TPU. 


The DEBUG file is compiled and executed (if available). 
TPU$INIT PROCEDURE is executed (if available). 

The Command buffer is compiled and executed (if available). 
TPUS$INIT_POSTPROCEDURE is executed (if available). 


nu BF Ww 


Note 


If you call this routine after calling TRU$CLEANUP, you must set 
the flags TRPU$ EXECUTEPROCEDURE and TPU$ EXECUTEFILE. 
Otherwise, the initialization file does not execute. 
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Condition Values Returned 


TPU$ SUCCESS Normal successful completion. 

TPU$ COMPILEFAIL The compilation of the initialization file was 
unsuccessful. 

TPU$ EXECUTEFAIL The execution of the statements in the 
initialization file was unsuccessful. 

TPU$ EXITING A result of EXIT. If the default condition handler 
is being used, the session is terminated. 

TPU$ FAILURE General code for all other errors. 

TPU$ QUITTING A result of QUIT. If the default condition handler 


is being used, the session is terminated. 
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TPU$FILEIO—Perform File Operations 


The TPU$FILEIO routine handles all DECTPU file operations. Your own file 
1/O routine can call this routine to perform some operations for it. However, the 
routine that opens the file must perform all operations for that file. For example, 
if TPU$FILEIO opens the file, it must also close it. 


Format 
TPU$FILEIO code ,stream ,data 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
code 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item code specifying a DECTPU function. The code argument is the address of a 
longword containing an item code from DECTPU specifying a function to perform. 
Following are the item codes that you can specify in the file I/O routine: 


e TPU$K_OPEN—This item code specifies that the data parameter is the 
address of an item list. This item list contains the information necessary 
to open the file. The stream parameter should be filled in with a unique 
identifying value to be used for all future references to this file’ The resultant 
file name should also be copied with a dynamic string descriptor. 


e TPU$K CLOSE—The file specified by the stream argument is to be closed. 
All memory being used by its structures can be released. 


e TPU$K CLOSE DELETE—The file specified by the stream argument is 
to be closed and deleted. All memory being used by its structures can be 
released. 


e TPU$K_GET—The data parameter is the address of a dynamic string 
descriptor to be filled with the next record from the file specified by the 
stream argument. The routine should use the routines provided by the Run- 
Time Library to copy text into this descriptor. DECTPU frees the memory 
allocated for the data read when the file |/O routine indicates that the end of 
the file has been reached. 


e TPU$K_PUT—The data parameter is the address of a descriptor for the data 
to be written to the file specified by the stream argument. 
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stream 
OpenVMS usage: unspecified 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


File description. The stream argument is the address of a data structure 
consisting of four longwords. This data structure describes the file to be 
manipulated. 


This data structure is used to refer to all files. It is written to when an open file 
request is made. All other requests use information in this structure to determine 
which file is being referenced. 


The following figure shows the stream data structure: 


File Identifier 


Address of name 


ZK-4045-GE 


The first longword holds a unique identifier for each file. The user-written file |/O 
routine is restricted to values between 0 and 511. Thus, you can have up to 512 
files open simultaneously. 


The second longword is divided into three fields. The low word is used to store 
the allocation quantity, that is, the number of blocks allocated to this file from 
the FAB (FAB$L_ALQ). This value is used later to calculate the output file size 
for preallocation of disk space. The low-order byte of the second word is used 

to store the record attribute byte (FAB$B_ RAT) when an existing file is opened. 
The high-order byte is used to store the record format byte (FAB$B_RFM) when 
an existing file is opened. The values in the low word and the low-order and 
high-order bytes of the second word are used for creating the output file in the 
same format as the input file. These three fields are to be filled in by the routine 
opening the file. 


The last two longwords are used as a descriptor for the resultant or the expanded 
file name. This name is used later when DECTPU processes EXIT commands. 
This descriptor is to be filled in with the file name after an open operation. It 
should be allocated with either the routine LIB$SCOPY_R_DX or the routine 
LIB$SCOPY_DX from the Run-Time Library. This space is freed by DECTPU 
when it is no longer needed. 


data 

OpenVMS usage: item _list_3 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Stream data. The data argument is either the address of an item list or the 
address of a descriptor. 
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Note 


The meaning of this parameter depends on the item code specified in the 
code field. 


When the TPU$K_OPEN item code is issued, the data parameter is the address 
of an item list containing information about the open request. The following 
DECTPU item codes are available for specifying information about the open 
request: 


TPU$K_ACCESS item code lets you specify one of three item codes in the 
buffer address field, as follows: 


- TPU$K_1O 
- TPU$K_INPUT 
- TPU$K_OUTPUT 


TPU$K_FILENAME item code is used for specifying the address of a string 
to use as the name of the file you are opening. The length field contains the 
length of this string, and the address field contains the address. 


TPU$K_DEFAULTFILE item code is used for assigning a default file name 
to the file being opened. The buffer length field contains the length, and the 
buffer address field contains the address of the default file name. 


TPU$K_RELATEDFILE item code is used for specifying a related file name 
for the file being opened. The buffer length field contains the length, and the 
buffer address field contains the address of a string to use as the related file 
name. 


TPU$K_ RECORD _ATTR item code specifies that the buffer address field 
contains the value for the record attribute byte in the FAB (FAB$B_RAT) 
used for file creation. 


TPU$K_RECORD_FORM item code specifies that the buffer address field 
contains the value for the record format byte in the FAB (FAB$B_RFM) used 
for file creation. 


TPU$K_MAXIMIZE_VER item code specifies that the version number of the 
output file should be one higher than the highest existing version number. 


TPU$K_FLUSH item code specifies that the file should have every record 
flushed after it is written. 


TPU$K_FILESIZE item code is used for specifying a value to be used as the 
allocation quantity when creating the file. The value is specified in the buffer 
address field. 
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By default, TPU$FILEIO creates variable-length files with carriage-return record 
attributes (FAB$B_RFM =VAR, FAB$B_RAT =CR). If you pass to it the TPU$K_ 
RECORD_ATTR or TPU$K_RECORD_FORM item, that item is used instead. 


The following combinations of formats and attributes are acceptable: 


Format Attributes 
STM,STMLF,STMCR 0,BLK,CR,BLK+CR 
VAR 0,BLK,FTN,CR,BLK+FTN,BLK+CR 


All other combinations are converted to VAR format with CR attributes. 


This routine always puts values greater than 511 in the first longword of the 
stream data structure. Because a user-written file 1/O routine is restricted to the 
values 0 through 511, you can easily distinguish the file control blocks (FCB) this 
routine fills in from the ones you created. 


Note 


DECTPU uses TPU$FILEIO by default when you use the simplified 
callable interface. When you use the full callable interface, you must 
explicitly invoke TPU$FILEIO or provide your own file |/O routine. 


Condition Values Returned 


The TPU$FILEIO routine returns an OpenVMS RMS status code to DECTPU. 
The file |/O routine is responsible for signaling all errors if any messages are 
desired. 
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TPU$FILE_PARSE— Parse the Given File Specification 


Format 


Returns 


Arguments 


The TPU$FILE_PARSE routine provides a simplified interface to the $PARSE 
system service. DECTPU calls this routine when the built-in procedure FILE_ 
PARSE is executed from TPU code. 


TPU$FILE_PARSE _ result-string ,flags ,filespec ,default-spec ,related-spec 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
See Condition Values Returned. 


result-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Includes the components of the file specification specified by the flags argument. 
The memory for the return string is allocated via the Run-Time Library routine 
LIB$SGET1_DD. Use the Run-Time Library routine LIB$SFREE1 DD to 
deallocate the memory for the return string. 


flags 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Determine what file specification components should be returned. The following 
table shows the valid values for the flags argument: 


Flag Bit’ Description 

TPU$M_ NODE Returns the node component of the file 
specification. 

TPU$M_ DEV Returns the device component of the file 
specification. 

TPU$M_DIR Returns the directory component of the file 
specification. 

TPU$M_ NAME Returns the name component of the file 
specification. 

1TPU$M ... indicates a mask. There is a corresponding value for each mask in the form TPU$V .... 
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Flag Bit' Description 

TPU$M_TYPE Returns the type component of the file 
specification. 

TPU$M_ VER Returns the version component of the file 
specification. 

TPU$M HEAD Returns NODE, DEVICE and DIRECTORY 
components of the file specification. If the 
TPU$M_ NODE, TPU$M_DEV or TPU$M_DIR 
bits are set while TPU$M_HEAD is set, the 
routine signals the error TPU$_INCKWDCOM 
and returns control to the caller. 

TPU$M_TAIL Returns NAME, TYPE and VERSION components 
of the file specification. If the TRU$M_ NAME, 
TPU$M_TYPE or TPU$M_VER bits are set while 
TPU$M_TAIL is set, the routine signals the error 
TPU$ INCKWDCOM and returns control to the 
caller. 

I1TPU$M ... indicates a mask. There is a corresponding value for each mask in the form TPU$V .... 

filespec 

OpenVMS usage:  char_string 

type: character string 

access: read only 

mechanism: by descriptor 


The object file specification. 


default-spec 
OpenVMS usage: 
type: 

access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


Contains the default file specification. The default file specification fields are used 
in the result string as substitutes for fields omitted in the filespec argument. 
You can also make substitutions in the result string using the related-spec 


argument. 


Use the value 0 when no default-spec is to be applied to the file specification. 


related-spec 
OpenVMS usage: 
type: 

access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


Contains the related file specification. The fields in the related file specification 
are substituted in the result-string if a particular field is missing from both the 
filespec and default-spec arguments. 


Use the value 0 when no default-spec is to be applied to the file specification. 
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Description 


The TPU$FILE_ PARSE routine returns a string containing the fields requested 
of the file specified. The file is not required to exist when the parse is done. 
The intention of the TPU$FILE_PARSE routine is to construct a valid file 
specification from the information passed in through the file specification, the 
default file specification, and the related file specification. 


The routine uses the $PARSE system service to return the requested information. 


The TPU$FILE_ PARSE routine is also called by DECTPU when the TPU built-in 
procedure FILE PARSE is executed from TPU code The return value of the 
built-in procedure is the string returned in the result-string argument. 


Condition Values Returned 


TPU$ SUCCESS Normal successful completion. If the return 
string contains a null-string, then the last match 
of the search operations has occurred. 


TPU$ INCKWDCOM The flags argument had an illegal combination 
of values. 
TPU$ PARSEFAIL The parse failed. 
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TPU$FILE_SEARCH—Search File System for Specified File 


The TPU$FILE_ SEARCH routine provides a simplified interface to the $5EARCH 
system service. DECTPU call this routine when TPU code executes the FILE_ 
SEARCH built-in procedure. 


Format 
TPU$FILE_SEARCH _ result-string ,flags ,filespec ,default-spec ,related-spec 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
See Condition Values Returned. 
Arguments 


result-string 
OpenVMS usage:  char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Includes the components of the file specification passed by the flags argument. 
The memory for the return string is allocated via the Run-Time Library routine 
LIB$SGET1_DD. To deallocate memory for the string, use the Run-Time Library 
routine LIB$SFREE1 DD. 


flags 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Determines what file specification components should be returned. The following 
table lists the valid flag values: 


Flag! Function 

TPU$M_ NODE Returns the node component of the file 
specification. 

TPU$M_DEV Returns the device component of the file 
specification. 

TPU$M_DIR Returns the directory component of the file 
specification. 

TPU$M_ NAME Returns the name component of the file 
specification. 

I1TPU$M ... indicates a mask. There is a corresponding value for each mask in the form TPU$V .... 
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Flag! Function 

TPU$M_TYPE Returns the type component of the file 
specification. 

TPU$M VER Returns the version component of the file 
specification. 


TPU$M_REPARSE 


Reparses the file specification before processing. 
This is intended to be used to reset the file search. 


TPU$M HEAD Returns NODE, DEVICE, and DIRECTORY 
components of the file specification. If the 
TPU$M NODE, TPU$M_DEV or TPU$M_DIR bits 
are set while TPU$M_HEAD is set, the routine 
will signal the error TPU$ INCKWDCOM and 
return. 

TPU$M_TAIL Returns NAME, TYPE and VERSION components 
of the file specification. If the TRU$M_NAME, 
TPU$M_TYPE or TPU$M_VER bits are set while 
TPU$M_TAIL is set, the routine will signal the 
error TPU$ INCKWDCOM and return. 

1TPU$M ... indicates a mask. Thereis a corresponding value for each mask in the form TPU$V .... 

filespec 

OpenVMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 


Object file specification. 


default-spec 
OpenVMS usage: 
type: 

access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


The default file specification. The default file specification fields are used to fill 
in the result-string when fields are omitted in the filespec argument. Use the 
related-spec argument to specify other substitutions. 


Use the value 0 when no default-spec is to be applied to the file specification. 


related-spec 
OpenVMS usage: 
type: 

access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


Contains the related file specification. The fields in the related file specification 
are used in the result-string for fields omitted in the filespec and default-spec 


arguments. 


Use the value 0 when no default-spec is to be applied to the file specification. 
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Description 


This routine allows an application to verify the existence of, and return 
components of, a file specification. Wildcard operations are permitted. The 
routine uses the $PARSE and $SEARCH system services to seek the file 
specification. 


If no wildcards are included in the file specification string and the result-string 
returns a zero (0) length string, no file was found. If wildcard characters were 
present in the file specification and the result-string returns a zero (0) length 
string, there are no more files that match the wildcards. 


To find all the files that match a wildcard specification, repeatedly call this 
routine, passing the same arguments, until the routine returns a zero-length 
result string. 


The TPU$FILE_ SEARCH routine is called by DECTPU when the TPU built-in 
procedure FILE SEARCH is executed from TPU code. The return value of the 
built-in procedure is the string returned in the result-string argument. 


Condition Values Returned 
TPU$ SUCCESS Normal successful completion. If the return 


string contains a null string, the final match 
operation was detected. 


TPU$ INCKWDCOM The flags argument had an illegal combination 
of values. 

TPU$ PARSEFAIL The requested repeat parse failed. 

TPU$ SEARCHFAIL An error occurred during the search operation. 
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TPU$SHANDLER—DECTPU Condition Handler 


The TPU$HANDLER routine is the DECTPU condition handler. 


The DECTPU condition handler invokes the $P UTMSG system service, passing it 
the address of TRU$MESSAGE. 


Format 
TPU$HANDLER - signal_vector ,mechanism_vector 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
See Condition Values Returned. 
Arguments 
signal_vector 
OpenVMS usage: arg list 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Signal vector. See the HP OpenVMS Systen Services Reference Manual for 
information about the signal vector passed to a condition handler. 
mechanism_vector 
OpenVMS usage: arg list 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Mechanism vector. See the HP OpenVMS System Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 
Description 


The TPU$MESSAGE routine performs the actual output of the message. The 
$PUTMSG system service only formats the message. It gets the settings for the 
message flags and facility name from the variables described in Section 8.1.2. 
Those values can be modified only by the DECTPU built-in procedure SET. 


If the condition value received by the handler has a FATAL status or does not 
have the DECTPU facility code, the condition is resignaled. 


If the condition is TPU$ QUITTING, TPU$ EXITING, or TPU$ RECOVERFAIL, 
a request to UNWIND is made to the establisher of the condition handler. 


After handling the message, the condition handler returns with a continue 
status. DECTPU error message requests are made by signaling a condition to 
indicate which message should be written out. The arguments in the signal 
array area correctly formatted message argument vector. This vector sometimes 
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contains multiple conditions and formatted ASCII output (FAO) arguments for 
the associated messages. For example, if the editor attempts to open a file that 
does not exist, the DECTPU message TPU$ NOFILEACCESS is signaled. The 
FAO argument to this message is a string for the name of the file. This condition 
has an error status, followed by the OpenVMS RMS status field (STS) and status 
value field (STV). Because this condition does not have a fatal severity, the editor 
continues after handling the error. 


The editor does not automatically return from TPU$CONTROL. If you call the 
TPU$CONTROL routine, you must explicitly establish a way to regain control 
(for example, using the built-in procedure CALL_USER). If you establish your 
own condition handler but call the DECTPU handler for certain conditions, 
the default condition handler must be established at the point in your program 
where you want to return control. You can also interrupt TPU$CONTROL 

by having your program specify and then trigger an asynchronous routine via 
the TPU$SPECIFY_ASNYC_ ACTION and TPU$TRIGGER_ASYNC ACTION 
routines. 


See the HP OpenVMS Calling Standard for details on writing a condition 
handler. 
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TPUSINITIALIZE—Initialize DECTPU for Processing 


Format 


Returns 


Argument 


The TPUS$INITIALIZE routine initializes DECTPU for text processing. This 

routine allocates global data structures, initializes global variables, and calls 
the appropriate setup routines for each of the major components of the editor, 
including the Screen Manager and the 1/O subsystem. 


TPUS$INITIALIZE callback [,user_arg] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


callback 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 

mechanism: by descriptor 


Callback routine. The callback argument is the address of a user-written routine 
that returns the address of an item list containing initialization parameters or 

a routine for handling file |/O operations. This callback routine must call a 
command line parsing routine, which can be TPU$CLIPARSE or a user-written 
parsing routine. 


Callable DECTPU defines item codes that you can use to specify initialization 
parameters. The following rules must be followed when building the item list: 


e If you use the TPU$ OTHER_FILENAMES item cade, it must follow the 
TPU$ FILENAME item code. 


e If you use either the TPU$ CHAIN item code or the TPU$ ENDLIST code, it 
must be the last item code in the list. 


The following figure shows the general format of an item descriptor. For 
information about how to build an item list, refer to the programmer’s manual 
associated with the language you are using. Any reference to command line 
qualifiers refer to those command line qualifiers that you use with the EDIT/TPU 
command. 
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Item code Buffer length 


Buffer address 


Return address 


ZK-4044-GE 


The return address in an item descriptor is usually 0. 


The following item codes are available: 


ltem Code 


Description 


TPU$ OPTIONS 


TPU$ J OURNALFILE 


TPU$ SECTIONFILE 


TPU$ OUTPUTFILE 


TPU$ DISPLAY FILE 


TPU$ COMMANDFILE 


TPU$ FILENAME 


Enables the command qualifiers. The bits in the bit mask 
specified by the buffer address field correspond to the various 
DECTPU command qualifiers. 


Passes the string specified with the // OURNAL qualifier. The 
buffer length field is the length of the string, and the buffer 
address field is the address of the string. This string is available 
with GET_INFO (COMMAND LINE,“J OURNAL FILE”). This 
string can be a null string. 


Passes the string that is the name of the binary initialization file 
(section file) to be mapped in. The buffer length field is the length 
of the string, and the buffer address field is the address of the 
string. If the TRU$V_SECTION bit is set, this item code must be 
specified. 

Passes the string specified with the (OUTPUT qualifier. The 
buffer length field is the length of the string, and the buffer 
address field specifies the address of the string. This string is 
returned by the built-in procedure GET_INFO (COMMAND_ 
LINE, “OUTPUT_FILE”). The string can be a null string. 


Passes the string specified with the /DISPLAY qualifier. The 
buffer length field defines the length of the string, and the buffer 
address field defines the string address. The interface between 
the TPUSHR image and the display file image is not documented. 
Applications should only use this option with documented display 
files such as TRPU$CCTSHR or TPUSMOTIFSHR. 


Passes the string specified with the (COMMAND qualifier. 
The buffer length field is the length of the string, and the 
buffer address field is the address of the string. This string is 
returned by the built-in procedure GET_INFO (COMMAND_ 
LINE, “COMMAND FILE”). The string can be a null string. 


Passes the string that is the name of the first input file specified 
on the command line. The buffer length field specifies the length 
of this string, and the buffer address field specifies its address. 
This string is returned by the built-in procedure GET_INFO 
(COMMAND LINE, “FIRST FILE NAME”). This file name can 
be a null string. 
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Item Code Description 

TPU$ OTHER_ Passes a string that contains the name of an input file that 

FILENAMES follows the first input file on the command line. The buffer length 
field specifies the length of this string, and the buffer address 
field specifies its address. Each additional file specified on the 
command line requires its ovn TPU$ OTHER_FILENAMES 
item entry. These strings are returned by the GET_INFO 
(COMMAND LINE,“NEXT_FILE_NAME”) built-in procedure 
in the order they appear in the item list. This item code must 
appear after the TPU$ FILENAME item in the item list. 

TPU$ FILEIO Passes the bound procedure value of a routine to be used for 


TPU$ CALLUSER 


TPU$ INIT_FILE 


TPU$ START_LINE 


TPU$ START_CHAR 


TPU$ CHARACTERSET 


handling file operations. You can provide your own file I/O 
routine, or you can call TPU$FILEIO, the utility routine provided 
by DECTPU for handling file operations. The buffer address field 
specifies the address of a two-longword vector. The first longword 
of the vector contains the address of the routine. The second 
longword specifies the environment value that DECTPU loads 
into R1 before calling the routine. 


Passes the bound procedure value of the user-written routine that 
the built-in procedure CALL_USER is to call. The buffer address 
field specifies the address of a two-longword vector. The first 
longword of the vector contains the address of the routine. The 
second longword specifies the environment value that DECTPU 
loads into R1 before calling the routine. 


Passes the string specified with the ANITIALIZATION qualifier. 
The buffer length field is the length of the string, and the buffer 
address field is the address of the string. This string is returned 
by the built-in procedure GET_INFO (COMMAND LINE,“INIT_ 
FILE”). 


Passes the starting line number for the edit. The buffer address 
field contains the first of the two integer values you specified as 
part of the /START_ POSITION command qualifier. The value is 
available using the built-in procedure GET_INFO (COMMAND_ 
LINE,“LINE”). Usually an initialization procedure uses this 
information to set the starting position in the main editing buffer. 
The first line in the buffer is line 1. 


Passes the starting column position for the edit. The buffer 
address field contains the second of the two integer values you 
specified as part of the /START_ POSITION command qualifier. 
The value is available using the built-in procedure GET_INFO 
(COMMAND LINE, “CHARACTER’”). Usually an initialization 
procedure uses this information to set the starting position in the 
main editing buffer. The first column on a line to character 1. 


Passes the string specified with the /CHARACTER_SET qualifier. 
The buffer length field specifies the string length and the buffer 
address field specifies the string address. Valid strings are “DEC_ 
MCS” (the default value), “ISO _LATIN1”, and “GENERAL”. If the 
application tries to pass any other string, the routine signals an 
error and passes the default string (DEC_MCS). 
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ltem Code 


Description 


TPU$ WORKFILE 


TPU$ CHAIN 


TPU$ ENDLIST 
TPU$ PARENT_WIDGET 


TPU$ APPLICATION _ 
CONTEXT 


TPU$ DEFAULTSFILE 


TPU$ CTRL_C_ROUTINE 


TPU$ DEBUGFILE 


TPU$ FILE SEARCH 


TPU$ FILE_PARSE 


Passes the string specified with the WORK qualifier. The buffer 
length field specifies the string length and the buffer address 
specifies the string address. This string is available with GET_ 
INFO (COMMAND LINE, “WORK_FILE”). 


Passes the address of the next item list to the process specified by 
the buffer address field. 


Signals the end of the item list. 


Passes the appropriate parent widget when invoking the 

DE Cwindows version of the editor. This routine is not specified by 
the application; DECTPU invokes its own application shell. The 
widget address is passed in the buffer address field. This item 
code is only valid when using the DE Cwindows interface. 


Passes the application context to use with the TPU$ PARENT _ 
WIDGET. DECTPU defaults to its own application context. The 
buffer address field specifies the application context address. This 
item code is only valid when using the DE Cwindows interface. 


Specifies which file DECTPU uses to initialize the X defaults 
database. The buffer length field specifies the string length and 
the buffer address field specifies the string address. This item 
code is only valid when using the DE Cwindows interface. 


Passes the bound procedure value of a routine to be used for 
handling Ctrl/C asynchronous system traps (ASTs). DECTPU 
calls the routine when a Ctrl/C AST occurs. If the routine returns 
a FALSE value, DECTPU assumes that the Ctrl/C has been 
handled. If the routine returns a TRUE value, DECTPU aborts 
any currently executing DECTPU procedure. The buffer address 
field specifies the address of a two-longword vector. The first 
longword of the vector contains the address of the routine. The 
second longword specifies the environment value that DECTPU 
loads into R1 before calling the routine. 


Passes the string specified with the /DEBUG command qualifier. 
The buffer length field is the length of the string, and the buffer 
address field is the address of the string. 


Passes the bound procedure value of a routine to be used to 
replace the TPU$FILE_ SEARCH routine which is called when the 
built-in procedure FILE SEARCH is called from TPU code. See 
the description of the TPU$FILE_ SEARCH and the user routine 
FILE SEARCH for more information. 


Passes the bound procedure value of a routine to be used to 
replace the TPU$FILE_ PARSE routine which is called when the 
built-in procedure FILE PARSE is called from TPU code. See 
the description of the TPU$FILE PARSE and the user routine 
FILE _PARSE for more information. 


Table 8-1 lists the bits and corresponding masks enabled by the item code 
TPU$K_OPTIONS and shows how each bit affects TPU$INITIALIZE operation. 
Several bits in the TRPU$ OPTIONS mask require additional item code entries 
in the item list. An example of this is TRU$M_ COMMAND which requires a 
TPU$ COMMANDFILE entry in the item list. 
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Table 8—1 Valid Masks for the TPU$K_OPTIONS Item Code 


GET_INFO 
Mask' Request String? Description 
TPU$M_ COMMAND COMMAND If DECTPU senses the presence of the TPU$_ 


TPU$M_COMMAND_ 
DFLTED 


TPU$M_CREATE 


TPU$M_DEBUG 


TPU$M_DEFAULTS 


TPU$M_DISPLAY 


TPU$M_INIT 


TPU$M_J OURNAL 


Not applicable 


CREATE 


Not applicable 


Not applicable 


DISPLAY 


INITIALIZATION 


J OURNAL 


COMMANDEFILE item, it tries to read, compile 
and execute the unbound TPU code. 


Specifies that DECTPU should use the default 
command file name of TRPUS$COMMAND.TPU 
when reading in the command file. No error is 
reported if the default command file is not found. 
TPUS$INITIALIZE fails when the TPU$M _ 
COMMAND_DFLTED bit is set to 0 and no file 
is specified in the item list. 

The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


If DECTPU senses the presence of the TPU$_ 
DEBUGFILE item, it tries to read the file, 
and then proceeds to compile and execute its 
contents as TPU statements. 


If DECTPU senses the presence of the TPU$_ 
DEFAULTSFILE item, it uses the specified 
DECwindows X resource file to initialize the 
DE Cwindows X resource database. 


If DECTPU senses the presence of the TPU$_ 
DISPLAY FILE item, it tries to image activate 
the specified image as its screen manager. 
When the bit is 0, DECTPU uses SYS$OUTPUT 
for display and only the READ _LINE built-in 
procedure may be used for input. 


If DECTPU senses the presence of the TPU$_ 
INIT_FILE item, it returns the specified string 
through the built-in procedure GET_INFO 
(COMMAND LINE, “INITIALIZATION_FILE”). 
Processing of the initialization file is left to the 
application. 

If DECTPU senses the presence of the TPU$_ 

J OURNALFILE item, it outputs the keystrokes 
entered during the editing session to the 
specified file. 

Note: HP recommends the use of buffer change 
journaling in new applications. 


1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit is 


set. TPU$V_ isa bit number. 


2Most bits in the mask have a corresponding GET_INFO (COMMAND LINE) request string. 


(continued on next page) 
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Table 8—1 (Cont.) Valid Masks for the TPU$K_OPTIONS Item Code 


Mask’ 


GET_INFO 
Request String? 


Description 


TPU$M_MODIFY 


TPU$M_ 
NODEFAULTS 


TPU$M_NOMODIFY 


TPU$M_OUTPUT 


TPU$M_READ 


TPU$M_RECOVER 


TPU$M_SECTION 


TPU$M_SEC_LNM_ 
MODE 


TPU$M_WORK 


TPU$M_WRITE 


MODIFY 


Not applicable 


NOMODIFY 


OUTPUT 


READ_ONLY 


RECOVER 


SECTION 


Not applicable 


WORK 


WRITE 


The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


DECTPU initializes the DE Cwindows X resource 
database only with resource files that the 

DE Cwindows toolkit routine XtAppll nitialize 
loads into the database 


The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


If DECTPU senses the presence of the TPU$_ 
SECTIONFILE item, it tries to read the 
specified file as a binary initialization file. 
TPUS$INITIALIZE fails if this bit is set to 1 and 
the TPU$ SECTIONFILE item is not present in 
the item list. 


If DECTPU senses the presence of the TPU$M _ 
SEC_LNM_MODE item, it looks only at 
executive mode logical names when attempting 
to read in a section file. 


If DECTPU senses the presence of the TPU$_ 
WORKFILE item, it uses the specifed file for 
memory management. If no item list entry is 
present, and this bit is set to 1, a file is created 
in SYS$LOGIN:.TPUSWORK. 


The behavior of DECTPU is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit is 


set. TPU$V_ isa bit number. 


2Most bits in the mask have a corresponding GET_INFO (COMMAND LINE) request string. 


To create the bits, start with the value 0, then use the OR operator on the mask 
(TPU$M ... ) of each item you want to set. Another way to create the bits is to 
treat the 32 bits as a bit vector and set the bit (TPU$V ... ) corresponding to the 
item you want. 
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user_arg 
OpenVMS usage: user_arg 
type: longword (unsigned) 
access: read only 
mechanism: by value 


User argument. The user_arg argument is passed to the user-written 
initialization routine INITIALIZE. 


The user_arg parameter is provided to allow an application to pass information 
through TPUS$INITIALIZE to the user-written initialization routine. DECTPU 
does not interpret this data in any way. 


Description 
This is the first routine that must be called after establishing a condition handler. 


This routine initializes the editor according to the information received from 
the callback routine. The initialization routine defaults all file specifications to 
the null string and all options to off. However, it does not default the file I/O or 
call-user routine addresses. 


Condition Values Returned 


TPU$ SUCCESS Initialization was completed successfully. 

TPU$ FAILURE General code for all other errors during 
initialization. 

TPU$ INSVIRMEM Insufficient virtual memory exists for the editor 
to initialize. 

TPU$ NOFILEROUTINE No routine has been established to perform file 
operations. 

TPU$ NONANSICRT The input device (SYS$INPUT) is not a 
supported terminal. 

TPU$ RESTOREFAIL An error occurred during the restore operation. 

TPU$ SYSERROR A system service did not work correctly. 
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TPUSMESSAGE—Write Message String 


Format 


Returns 


Argument 


The TPU$MESSAGE routine writes error messages and strings using the built-in 
procedure, MESSAGE. 


Call this routine to have messages written and handled in a manner consistent 
with DECTPU. This routine should be used only after TRU$EXECUTE_INIFILE. 


TPU$MESSAGE string 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. 


Note 


The return status should be ignored because it is intended for use by the 
$PUTMSG system service. 


string 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Formatted message. The string argument is the address of a descriptor of text 
to be written. It must be completely formatted. This routine does not append 
the message prefixes. However, the text is appended to the message buffer if one 
exists. In addition, if the buffer is mapped to a window, the window is updated. 
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TPU$PARSEINFO—Parse Command Line and Build Item List 


Format 


Returns 


Arguments 


Description 


The TPU$PARSEINFO routine parses a command and builds the item list for 
TPUSINITIALIZE. 


TPU$PARSEINFO _fileio ,call_user 


OpenVMS usage: item_list 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


The routine returns the address of an item list. 


fileio 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 

mechanism: by descriptor 


File 1/O routine. The fileio argument is the address for a descriptor of a file 1/O 
routine. 


call_user 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 
access: read only 

mechanism: by descriptor 


Call-user routine. The call_user argument is the address for a descriptor of a 
call-user routine. 


The TPU$PARSEINFO routine parses a command and builds the item list for 
TPUSINITIALIZE. 


This routine uses the command language (CLI) routines to parse the current 
command. It makes queries about the command parameters and qualifiers that 
DECTPU expects. The results of these queries are used to set up the proper 
information in an item list. The addresses of the user routines are used for those 
items in the list. The address of this list is the return value of the routine. 


If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls the TRPU$PARSEINFO interface. This is 
because TPU$PARSEINFO destroys all parse information obtained and stored 
before TPU$PARSEINFO was called. 
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TPUS$SIGNAL—Signal a TPU Status 


Format 


Returns 


Argument 


Description 


The TPU$SIGNAL routine allows applications and user-written TPU routines 
such as FILEIO to easily signal error messages in order for TPU error handlers 
to perform correctly. 


TPU$SIGNAL — condition-code 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. In most cases, the routine returns either the same 
signal passed to it in the condition value argument, or the return value of 
LIB$SIGNAL. If the routine fails, it signals TPU$ FAILURE and returns control 
to the caller. 


condition-code 
OpenVMS usage: cond_value 


type: longword (unsigned) 
access: read only 
mechanism: by value 


The condition-code is an unsigned longword that contains the condition code to be 
signaled. In most cases, this argument is a TPU message code. 


TPU$SIGNAL performs the same function as the Run-Time Library routine 
LIB$SIGNAL, but it also processes TPU facility messages to allow TPU language 
ON_ERROR handlers to be called. 


For example, assume that a user-written file input/output routine is designed 
to signal the error TRPU$ OPENIN when it fails to open a file. Calling the 
TPU$SIGNAL routine and passing the value TPU$ OPENIN allows a casestyle 
TPU ON_ERROR handler to receive the error, thus preserving the documented 
return values for TPU built-in procedures such as READ FILE. 


Note 


You must call TPU$INITIALIZE before you call the TPU$SIGNAL 
routine. 


If TPU$ QUITTING, TPU$ EXITING, or TRPU$ RECOVERFAIL are passed to 
the routine, it calls the Run-Time Library routine LIB$SIGNAL. 


If facility messages other than TPU messages are passed to the TPU$SIGNAL 
routine, it calls the LIB$SIGNAL routine and passes the appropriate condition 
value. 
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TPU$SSPECIFY_ASYNC_ACTION—Register an Asynchronous Action 


The TPU$SPECIFY_ASYNC ACTION routine allows applications using the 
DECTPU full callable interface to register asynchronous actions with DECTPU. 


Format 
TPU$SPECIFY_ASYNC_ACTION _ facility_index [,tou_statement] 

Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 
facility_index 
OpenVMS usage: longword_unsigned 
type: longword (signed) 
access: read only 
mechanism: by reference 
Represents an index of the asynchronous action. This index is used with the 
TPU$TRIGGER_ASYNC ACTION routine to let DECTPU know what action to 
perform. It may also be used to delete an action routine (by omitting the tpu_ 
statement). You may register several asynchronous actions depending on your 
application’s needs. This facility index number may be any positive integer. 
tpu_statement 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
The DECTPU statement you want executed when you call the TRU$TRIGGER_ 
ASYNC_ACTION routine. The statement is compiled and then stored internally. 
If you omit the parameter, DECTPU removes the action from its list of 
asynchronous events. 

Description 


The TPU$SPECIFY_ASYNC ACTION routine, along with TPU$TRIGGER_ 
ASYNC_ACTION, allow applications to interrupt DECTPU after calling 
TPU$CONTROL. The specified DECTPU statement is compiled and saved. 


This routine must be called after TPUSINITIALIZE. It will not complete 
successfully if keystroke journaling is enabled. 
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Condition Values Returned 


TPU$ SUCCESS Normal successful completion. 

TPU$ COMPILEFAIL The code specified in tpu_statement did not 
compile successfully. 

TPU$ INVPARM An invalid parameter was passed. 

TPU$ J NLACTIVE Keystroke journaling is active. This routine 


requires that either journaling be turned off or 
that buffer change journaling be used. 
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TPU$TPU—Invoke DECTPU 


The TPU$TPU routine invokes DECTPU and is equivalent to the DCL command 


EDIT/TPU. 
Format 
TPU$TPU command 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Argument 
command 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 
Command string. Note that the verb is TPU instead of EDIT/TPU. The 
command argument is the address for a descriptor of a command line. 
Description 


This routine takes the command string specified and passes it to the editor. 
DECTPU uses the information from this command string for initialization 
purposes, just as though you had entered the command at the DCL level. 


Using the simplified callable interface does not set TPU$CLOSE SECTION. This 
feature lets you make multiple calls to TPU$TPU without requiring you to open 
and close the section file on each call. 


If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TPU$TPU. This is because TPU$TPU 
destroys all parse information obtained and stored before TPU$TPU was called. 


Condition Values Returned 


This routine returns any condition value returned by TPU$INITIALIZE, 
TPU$EXECUTE_INIFILE, TRPU$CONTROL, and TPU$CLEANUP. 
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TPU$TRIGGER_ASYNC_ACTION—Execute DECTPU Command at 


Format 


Returns 


Arguments 


Description 


Asynchronous Level 


The TPU$TRIGGER_ASYNC ACTION routine allows applications using the 
DECTPU full callable interface to interrupt the DECTPU TPU$CONTROL loop 
at an asynchronous level. 


TPU$TRIGGER_ASYNC_ACTION _ facility_index 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


facility_index 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


The facility_index argument represents the asynchronous action to be taken. 
This is the same index passed to the TRU$SPECIFY_ASYNC ACTION routine 
registering what DECTPU statements to execute. 


The TPU$TRIGGER_ASYNC_ ACTION routine, along with TPU$SPECIFY_ 
ASYNC_ACTION routine allow applications to interrupt DECTPU after calling 
TPU$CONTROL. The command that was specified for this facility_index is 
put on the DECTPU queue of work items and is handled as soon as no other 
work items are present. This allows DECTPU to complete and stabilize its 
environment before executing the command. This routine must be called after 
control has been passed to DECTPU via the TRU$CONTROL routine. 


Condition Values Returned 


TPU$ SUCCESS Normal successful completion. 


TPU$ UNKFACILITY The facility_index passed to this routine 
does not match any facility index passed to 
TPU$SPECIFY_ASYNC ACTION. 
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FILEIO—User-Written Routine to Perform File Operations 


Format 


Returns 


Arguments 


The user-written FILEIO routine is used to handle DECTPU file operations. The 
name of this routine can be either your own file 1/O routine or the name of the 
DECTPU file I/O routine (TPU$FILEIO). 


FILEIO code ,stream ,data 


OpenVMS usage: cond_value 


type: longword (usigned) 
access: write only 
mechanism: by reference 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


code 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item code specifying a DECTPU function. The code argument is the address of 
a longword containing an item code from DECTPU, which specifies a function to 
perform. 


stream 

OpenVMS usage: unspecified 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


File description. The stream argument is the address of a data structure 
containing four longwords. This data structure is used to describe the file to be 
manipulated. 


data 

OpenVMS usage: item_list_3 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Stream data. The data argument is either the address of an item list or the 
address of a descriptor. 


Note 


The value of this parameter depends on which item code you specify. 
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Description 


The bound procedure value of this routine is specified in the item list built by 
the callback routine. This routine is called to perform file operations. Instead 

of using your own file I/O routine, you can call TPU$FILEIO and pass it the 
parameters for any file operation you do not want to handle. Note, however, that 
TPU$FILEIO must handle all I/O requests for any file it opens. Also, if it does 
not open the file, it cannot handle any I/O requests for the file. |n other words, 
you cannot mix the file operations between your own file 1/O routine and the one 
supplied by DECTPU. 


Condition Values Returned 


The condition values returned are determined by the user and should indicate 
success or failure of the operation. 
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FILE_PARSE—User-Written Routine to Perform File Parse 


Operations 
This is a user-written routine that can be used in place of the TPU$FILE_ PARSE 
routine. 
Format 
FILE PARSE _ result-string ,flags ,filespec ,default-spec ,related-spec 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. The return value is ignored by DECTPU. User-written 
FILE _PARSE routines should include calls to the TPU$SIGNAL routine to ensure 
proper error handling. 
Arguments 


result-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Return value for the built-in procedure FILE PARSE. The calling program should 
fill in this descriptor with a dynamic string allocated by the string routines, such 
as the Run-Time Library routine LIB$SGET1 DD. DECTPU frees this string 
when necessary. 


flags 

OpenVMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

The following table lists the valid flag values used to request file specification 

components: 

Flag! Function 

TPU$M_ NODE Requests for the node component of the file 
specification. 

TPU$M_ DEV Requests for the device component of the file 
specification. 

TPU$M_DIR Requests for the directory component of the file 
specification. 

1TPU$M ... indicates a mask. Thereis a corresponding value for each mask in the form TPU$V .... 
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Flag! Function 

TPU$M_ NAME Requests for the name component of the file 
specification. 

TPU$M_TYPE Requests for the type component of the file 
specification. 

TPU$M_VER Requests for the version component of the file 
specification. 

TPU$M HEAD Requests for the NODE, DEVICE, and 
DIRECTORY components of the file specification. 

TPU$M_TAIL Requests for NAME, TYPE, and VERSION 
components of the file specification. 

I1TPU$M ... indicates a mask. There is a corresponding value for each mask in the form TPU$V .... 

filespec 

OpenVMS usage:  char_string 

type: character string 

access: read only 

mechanism: by descriptor 


The object file specification. 


default-spec 


OpenVMS usage:  char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Contains the default file specification. The value 0 is passed if there is no 
default-spec argument. 


related-spec 


OpenVMS usage:  char_string 
type: character string 
access: read only 
mechanism: by descriptor 


The related-spec argument contains the related file specification. The value 0 is 
passed if there is no related-spec. 


This routine allows an application to replace the TPU$FILE PARSE routine 
with its own file-parsing routine. The calling program passes the address of the 
fileparsing routine to TPU$INITIALIZE using the TPU$ FILE PARSE item 


code. 


When the DECTPU built-in procedure FILE_PARSE is called from TPU 
code, DECTPU calls either the user-written routine (if one was passed to 
TPU$INITIALIZE) or the TRU$FILE_PARSE routine. The return value of 
the built-in procedure is the string returned in the result-string argument. 


To ensure proper operation of the user’s ON_ERROR error handlers, errors should 
be signaled using the TPU$SIGNAL routine 
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FILE_ SEARCH—User-Written Routine to Perform File Search 


Operations 
This is a user-written routine that is used in place of the TPU$FILE_ SEARCH 
routine. 
Format 
FILE SEARCH - result-string ,flags ,filespec ,default-spec ,related-spec 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. If an odd numeric value is returned, the next call to 
the built-in procedure FILE_SEARCH automatically sets the TPU$M_REPARSE 
bit in the flags longword. TPU$M_REPARSE is also set if the result-string has 
a length of 0. 
Arguments 


result-string 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by descriptor 


Return value for the built-in procedure FILE SEARCH. Your program should fill 
in this descriptor with a dynamic string allocated by the string routines such as 
the Run-Time Library routine LIB$SGET1 DD. DECTPU frees this string when 
necessary. 


The TPU$M_REPARSE bit is set in the flags longword if the result-string has a 
length of zero. The bit is intended to reset the file search when wildcard searches 
are performed. 


flags 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The following table shows the flags used for specifying the file components: 


Flag! Function 

TPU$M_ NODE Requests for the node component of the file 
specification. 

TPU$M_ DEV Requests for the device component of the file 
specification. 

1TPU$M ... indicates a mask. Thereis a corresponding value for each mask in the form TPU$V .... 
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FILE_SEARCH 

Flag! Function 

TPU$M_DIR Requests for the directory component of the file 
specification. 

TPU$M_ NAME Requests for the name component of the file 
specification. 

TPU$M_TYPE Requests for the type component of the file 
specification. 

TPU$M_ VER Requests for the version component of the file 
specification. 


TPU$M_REPARSE 


Reparses the file specification before processing. 
This is intended as a way to restart the file search. 
This flag will automatically be set by DECTPU 

if on a previous call to the FILE SEARCH user 
routine the result-string has a zero length or the 
routine returns a odd (noneven) status. 


TPU$M_ HEAD Requests for the NODE, DEVICE, and 
DIRECTORY components of the file specification. 

TPU$M_TAIL Requests for the NAME, TYPE, and VERSION 
component of the file specification. 

I1TPU$M ... indicates a mask. There is a corresponding value for each mask in the form TPU$V .... 

filespec 

OpenVMS usage:  char_string 

type: character string 

access: read only 

mechanism: by descriptor 


The object file specification. 


default-spec 
OpenVMS usage: 
type: 

access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


The default-spec argument contains the default file specification. 


The value 0 is passed if there is no default-spec. 


related-spec 
OpenVMS usage: 
type: 

access: 
mechanism: 


char_string 
character string 
read only 

by descriptor 


The related-spec argument contains the related file specification. 


The value 0 is passed if there is no related-spec. 
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Description 


The FILE SEARCH user routine allows an application to replace the TPU$FILE_ 
SEARCH routine with its own file-searching routine. The calling program passes 
the address of the routine to the TPU$INITIALIZE routine using the TPU$_ 
FILE SEARCH item code. 


When the DECTPU built-in procedure FILE SEARCH is called from TPU code, 
DECTPU calls either the user-written FILE SEARCH routine (if one was passed 
to TPUSINITIALIZE) or the TPU$FILE SEARCH routine. The return value of 
the built-in procedure is the string returned in the result-string argument. 


To ensure proper operation of the user’s ON ERROR handlers, errors in the 
user-written FILE PARSE routine should be signaled using the TPU$SIGNAL 
routine. 
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HANDLER—User-Written Condition Handling Routine 


Format 


Returns 


Arguments 


Description 


The user-written HANDLER routine performs condition handling. 


HANDLER § signal_vector ,mechanism_vector 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. 


signal_vector 
OpenVMS usage: arg list 


type: longword (unsigned) 
access: modify 
mechanism: by reference 


Signal vector. See the HP OpMVMS System Services Reference Manual for 
information about the signal vector passed to a condition handler. 


mechanism_vector 
OpenVMS usage: arg list 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Mechanism vector. See the HP OpenVMS Systen Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 


If you need more information about writing condition handlers and programming 
concepts, refer to HP OpenVMS Programming Concepts Manual. 


Instead of writing your own condition handler, you can use the default condition 
handler, TPU$HANDLER. If you want to write your own routine, you must call 
TPUSHANDLER with the same parameters that your routine received to handle 
DECTPU internal signals. 
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INITIALIZE—User-Written Initialization Routine 


The user-written initialization callback routine is passed to TPU$INITIALIZE 
as a bound procedure value and called to supply information needed to initialize 


DECTPU. 
Format 
INITIALIZE [user_arg] 
Returns 
OpenVMS usage: item list 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
This routine returns the address of an item list. 
Arguments 
user_arg 
OpenVMS usage: user_arg 
type: longword (unsigned) 
access: read only 
mechanism: by value 
User argument. 
Description 


The user-written initialization callback routine is passed to TPU$INITIALIZE 
as a bound procedure value and called to supply information needed to initialize 
DECTPU. 


If the user_arg parameter was specified in the call to TPU$INITIALIZE, the 
initialization callback routine is called with only that parameter. If user_arg 
was not specified in the call to TPU$INITIALIZE, the initialization callback 
routine is called with no parameters. 


The user_arg parameter is provided to allow an application to pass information 
through TPUS$INITIALIZE to the user-written initialization routine. DECTPU 
does not interpret this data in any way. 


The user-written callback routine is expected to return the address of an item 
list containing initialization parameters. Because the item list is used outside 
the scope of the initialization callback routine, it should be allocated in static 
memory. 


The item list entries are discussed in the section about TPU$INITIALIZE.. Most 
of the initialization parameters have a default value; strings default to the null 
string, and flags default to false. The only required initialization parameter is the 
address of a routine for file 1/O. If an entry for the file |/O routine address is not 
present in the item list, TPU$INITIALIZE returns with a failure status. 
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USER—User-Written Routine Called from a DECTPU Editing Session 


Format 


Returns 


Arguments 


The user-written USER routine allows your program to take control during 
a DECTPU editing session (for example, to leave the editor temporarily and 
perform a calculation). 


USER integer ,stringin ,stringout 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. 


integer 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


First parameter to the built-in procedure CALL_USER. This is an input-only 
parameter and must not be modified. 


stringin 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Second parameter to the built-in procedure CALL_USER. This is an input-only 
parameter and must not be modified. 


stringout 

OpenVMS usage: char_string 
type: character string 
access: modify 
mechanism: by descriptor 


Return value for the built-in procedure CALL_USER. Your program should fill 
in this descriptor with a dynamic string allocated by the string routines (such as 
LIB$SGET1_DD) provided by the Run-Time Library. The DECTPU editor frees 
this string when necessary. 
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Description 


This user-written routine is invoked by the DECTPU built-in procedure CALL _ 
USER. The built-in procedure CALL_USER passes three parameters to this 
routine. These parameters are then passed to the appropriate part of your 
application to be used as specified. (For example, they can be used as operands 
in a calculation within a Fortran program.) Using the string routines provided 
by the Run-Time Library, your application fills in the stringout parameter in 
the call-user routine, which returns the stringout value to the built-in procedure 
CALL_USER. 


The description of the built-in procedure CALL_USER in the DEC Text Processing 
Utility Reference Manual shows an example of a BASIC program that is a 
call-user routine. 


See Section 8.5 for a description of how to create an executeable image for the 
USER routine and how to call the routine from a C program in the DECTPU 
environment. 
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DECdts Portable Applications Programming 
Interface 


You can use the Digital Distributed Time Service (DE Cdts) programming routines 
to obtain timestamps that are based on Coordinated Universal Time (UTC). You 
can also use the DECdts routines to translate among different timestamp formats 
and perform calculations on timestamps. Applications can use the timestamps 
that DE Cdts supplies to determine event sequencing, duration, and scheduling. 
Applications can call the DECdts routines from DE Cdts server or clerk systems. 


The Digital Distributed Time Service routines are written in the C programming 
language. You should be familiar with the basic DECdts concepts before you 
attempt to use the applications programming interface (API). 


The DECdts API routines can perform the following basic functions: 

e Retrieve timestamp information 

*« Convert between binary timestamps that use different time structures 
e Convert between binary timestamps and ASCII representations 

e Convert between UTC time and local time 


e Convert the binary time values in the OpenVMS (Smithsonian-based) format 
to or from UTC-based binary timestamps (OpenVMS systems only) 


e Manipulate binary timestamps 

e« Compare two binary time values 
e Calculate binary time values 

e Obtain time zone information 


DECdts can convert between several types of binary time structures that 

are based on different calendars and time unit measurements. DECdts uses 
UTC-based time structures and can convert other types of time structures to its 
own presentation of UTC-based time. 


The following sections describe DECdts time representations, DE Cats time 
structures, API header files, and API routines. 


9.1 DECdts Time Representation 


UTC is the international time standard that has largely replaced Greenwich 
Mean Time (GMT). The standard is administered by the International Time 
Bureau (BIH) and is widely used. DECdts uses opaque binary timestamps that 
represent UTC for all of its internal processes. You cannot read or disassemble 
a DECdats binary timestamp; the DECdts API allows applications to convert or 
manipulate timestamps, but they cannot be displayed. DECdts also translates 
the binary timestamps into ASCII text strings, which can be displayed. 
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9.1.1 Absolute Time Representation 


An absolute time is a point on a time scale. For DECdts, absolute times 
reference the UTC time scale; absolute time measurements are derived from 
system clocks or external time-providers. When DECdts reads a system clock 
time, it records the time in an opaque binary timestamp that also includes the 
inaccuracy and other information. When you display an absolute time, DECadts 
converts the time to ASCII text, as shown in the following display: 


1996-11-21-13:30:25.785-04:001000.082 


DECats displays all times in a format that complies with the | nternational 
Standards Organization (|SO) 8601 (1988) standard. Note that the inaccuracy 
portion of the time is not defined in the |SO standard (times that do not include 
an inaccuracy are accepted). Figure 9-1 explains the |SO format that generated 
the previous display. 


Figure 9-1 Time Display Format 


Calendar date and time Inaccuracy 


TDF 
| component ii component “Hf component | 


CCYY-MM-DD-hh:mm:ss.fff[+|-]hh:mmIsss.ff£ 


seconds 
Inaccuracy 
designator | 
— minutes 


In Figure 9-1, the relative time preceded by the plus (+) or minus (-) character 
indicates the hours and minutes that the calendar date and time are offset from 
UTC. The presence of this time differential factor (TDF) in the string also 
indicates that the calendar date and time are the local time of the system, not 
UTC. Local time is UTC minus the TDF. The I naccuracy designator I indicates 
the beginning of the inaccuracy component associated with the time. 


Although DE Cdts displays all times in the previous format, variations in the |SO 
format shown in Figure 9-2 are also accepted as input for the ASCII conversion 
routines. 
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Figure 9-2 Time Display Format Variants 


Calendar date and time Inaccuracy 


TDF 
| component ia component all component | 


CCYY-MM-DDThh:mm:ss,fff[+|-]hh:mmtss, fff 


Centur 


seconds 


Inaccuracy 
designator 


Ti 


ime 
designator 


minutes 


ZK-4068A-GE 


In Figure 9-2, the Time designator T separates the calendar date from the time, 
a comma separates seconds from fractional seconds, and the plus or minus 
character indicates the beginning of the inaccuracy component. 


The following examples show some valid time formats. 


The following represents J uly 4, 1776 17:01 GMT and an infinite inaccuracy 
(default). 


1776-7-4-17:01:00 


The following represents a local time of 12:01 (17:01 GMT) on J uly 4, 1776 with a 
TDF of -5 hours and an inaccuracy of 100 seconds. 


1776-7-4-12:01:00-05:00I100 


Both of the following represent 12:00 GMT in the current day, month, and year 
with an infinite inaccuracy. 


12:00 and T12 
The following represents J uly 14, 1792 00:00 GMT with an infinite inaccuracy. 
1792-7-14 


9.1.2 Relative Time Representation 


A relative time is a discrete time interval that is usually added to or subtracted 
from another time. A TDF associated with an absolute time is one example of a 
relative time. A relative time is normally used as input for commands or system 
routines. 


Figure 9-3 shows the full syntax for a relative time. 
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Figure 9-3 Relative Time Syntax 


Relative date and time Inaccuracy 
component “| [ component 


DD-hh:mm:ss.fffIss.fff 


Inaccuracy 
designator 


ZK-4984A-GE 


Notice that a relative time does not use the calendar date fields, because these 
fields concern absolute time. A positive relative time is unsigned; a negative 
relative time is preceded by a minus (—) sign. A relative time is often subtracted 
from or added to another relative or absolute time. The relative times that 
DECdts uses internally are opaque binary timestamps. The DECdts API offers 
several routines that can be used to calculate new times using relative binary 
timestamps. 


The following example shows a relative time of 21 days, 8 hours, and 30 minutes, 
25 seconds with an inaccuracy of 0.300 second. 


21-08:30:25.000100.300 


The following example shows a negative relative time of 20.2 seconds with an 
infinite inaccuracy (default). 


-20.2 

The following example shows a relative time of 10 minutes, 15.1 seconds with an 
inaccuracy of 4 seconds. 

10:15.114 


Representing Periods of Time 
A given duration of a period of time can be represented by a data element of 
variable length that uses the syntax shown in Figure 9-4. 


Figure 9-4 Time Period Syntax 


PnYnM nWnDTnHnMnS In 


Zs a Inaccuracy Designator/Inaccuracy 
— a Seconds/Second Designator 
TE Minutes/Minute Designator 
Weeks/Week Designator 
: Hours/Hour Designator 
Days/Day Designator — Tene Designation 


ZK-4985A-GE 


The data element contains the following parts: 


e The designator P precedes the part that includes the calendar components, 
including the following: 


— The number of years followed by the designator Y 


— The number of months followed by the designator M 
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— The number of weeks followed by the designator W 
— The number of days followed by the designator D 


e The designator T precedes the part that includes the time components, 
including the following: 


— The number of hours followed by the designator H 
— The number of minutes followed by the designator M 
— The number of seconds followed by the designator s 
e The designator I precedes the number of seconds of inaccuracy. 


The following example represents a period of 1 year, 6 months, 15 days, 11 hours, 
30 minutes, and 30 seconds and an infinite inaccuracy. 


P1Y6M15DT11H30M30S 


The following example represents a period of 3 weeks and an inaccuracy of 4 
seconds. 


P3WI4 


9.2 Time Structures 


DECdts can convert between several types of binary time structures that are 
based on different base dates and time unit measurements. DECdts uses UTC- 
based time structures and can convert other types of time structures to its own 
presentation of UTC-based time. The DECdts API routines are used to perform 
these conversions for applications on your system. 


Table 9-1 lists the absolute time structures that the DECdts API uses to modify 
binary times for applications. 


Table 9-1 Absolute Time Structures 


Structure Time Units Base Date Approximate Range 
utc 100-nanosecond 15 October 1582 A.D. 1 to A.D. 30,000 
tm second 1J anuary 1900 A.D. 1 to A.D. 30,000 
timespec nanosecond 1) anuary 1970 A.D. 1970 to A.D. 2106 


Table 9-2 lists the relative time structures that the DECdts API uses to modify 
binary times for applications. 


Table 9-2 Relative Time Structures 


Structure Time Units Approximate Range 
utc 100-nanosecond + 30,000 years 

tm second + 30,000 years 
reltimespec nanosecond +68 years 


The remainder of this section explains the DECdts time structures in detail. 
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9.2.1 The utc Structure 


Coordinated Universal Time (UTC) is useful for measuring time across local time 
zones and for avoiding the seasonal changes (summer time or daylight saving 
time) that can affect the local time. DECdts uses 128-bit binary numbers to 
represent time values internally; throughout this manual, these binary numbers 
representing time values are referred to as binary timestamps. The DECdts 
utc structure determines the ordering of the bits in a binary timestamp; all 
binary timestamps that are based on the utc structure contain the following 
information: 


¢ The count of 100-nanosecond units since 00:00:00.00, 15 October 1582 (the 
date of the Gregorian reform to the Christian calendar) 


¢ Thecount of 100-nanosecond units of inaccuracy applied to the above 
e Thetime differential factor (TDF), expressed as the signed quantity 
e The timestamp version number 


The binary timestamps that are derived from the DECdts utc structure have an 
opaque format. This format is a cryptic character sequence that DE Cdts uses and 
stores internally. The opaque binary timestamp is designed for use in programs, 
protocols, and databases. 


Note 


Applications use the opaque binary timestamps when storing time values 
or when passing them to DE Cats. 


The API provides the necessary routines for converting between opaque binary 
timestamps and character strings that can be displayed and read by users. 


9.2.2 The tm Structure 


The tm structure is based on the time in years, months, days, hours, minutes, and 
seconds since 00:00:00 GMT (Greenwich Mean Time), 1 J anuary 1900. The tm 
structure is defined in the <time.h> header file 


The tm structure declaration follows: 


struct tm { 


int tm_sec; /* Seconds (0 - 59) */ 
int tm _min; /* Minutes (0 - 59) */ 
int tm_hour; /* Hours (0 - 23) */ 
int tmmday; /* Day of Month (1 - 31) */ 
int tm_mon; /* Month of Year (0 - 11) */ 
int tmyear; /* Year - 1900 */ 
int tmwday; /* Day of Week (Sunday = 0) */ 
int tm_yday; /* Day of Year (0 - 364) */ 
int tm_isdst; /* Nonzero if Daylight Savings Time */ 

/* is in effect */ 


i 


Not all of the tm structure fields are used for each routine that converts between 
tm structures and utc structures. See the parameter descriptions that accompany 
the routines in Chapter 9 for additional information about which fields are used 
for specific routines. 
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9.2.3 The timespec Structure 


The timespec structure is normally used in combination with or in place of the 
tm structure to provide finer resolution for binary times. The timespec structure 
is similar to the tm structure, but the timespec structure specifies the number of 
seconds and nanoseconds since the base time of 00:00:00 GMT, 1J anuary 1970. 
You can find the structure in the <utc.h> header file. 


The timespec structure declaration follows: 


struct timespec { 


unsigned long tv_sec; /* Seconds since 00:00:00 GMT, */ 
/* 1 January 1970 */ 
long tv_nsec; /* Additional nanoseconds since */ 
/*  tv_sec */ 
} timespec _t; 


9.2.4 The reltimespec Structure 


The reltimespec structure represents relative time. This structure is similar to 
the timespec structure, except that the first field is signed in the reltimespec 
structure. (The field is unsigned in the timespec structure.) You can find the 
reltimespec structure in the <utc.h> header file 


The reltimespec structure declaration follows: 


struct reltimespec { 


long tv_sec; /* Seconds of relative time */ 
long tv_nsec; /* Additional nanoseconds of */ 
/* relative time */ 


}  veltimespec t; 


9.2.5 The OpenVMS Time Structure 


The OpenVMS time structure is based on Smithsonian time, which has a base 
date of November 17, 1858. The binary OpenVMS structure is a signed, 64-bit 
integer that has a positive value for absolute times. You can use the DECdts API 
to translate an OpenVMS structure representing an absolute time to or from the 
DE Cdts UTC-based binary timestamp. 


9.3 DECdts API Header Files 


On OpenVMS systems, the header files are located in the SYS$LIBRARY 
directory. The <time.h> and <utc.h> header files contain the data structures, 
type definitions, and define statements that are referenced by the DECdts API 
routines. The <time.h> header file is present on all OpenVMS systems. The 
<utc.h> header file includes <time.h> and contains the timespec, reltimespec, 
and utc structures. 
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9.4 Linking Programs with the DECdts API 


The DECdts API is implemented by a shared image. To use the API with your 
program, you must link the program with this shared image. On DECnet-Plus 
for OpenVMS systems, the DECdts API is implemented by the shared image 
SYS$LIBRARY:DTSS$SHR.EXE. The following example shows how to link a 
program with the DE Cdts shared image: 


$ CC MYPROGRAM.C/OUTPUT=MYPROGRAM. OBJ 

$ LINK MYPROGRAM.OBJ, SYSSINPUT: /OPTIONS [Return] 
SYSSLIBRARY : DISSSSHR . EXE/ SHARE [Ctr-z 
$ 


9.5 DECdts API Routine Functions 


Figure 9-5 categorizes the DECdts portable interface routines by function. 
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Figure 9-5 DTS Portable Interface Categories 


Retrieving Time ... 


Converting Formats ... 


Converting Structures ... 


Manipulating Times... 


Comparing Times... 


Calculating Times. ... 


Obtaining Timezone 
Information... 


utc_gettime 
utc_getusertime 


To/From 
ASCII text: 


utc_ascanytime 
utc_ascgmtime 
utc_asclocaltime 
utc_ascreltime 
utc_mkasctime 
utc_mkascreltime 


To/From 
tm Structures: 


utc_anytime 
utc_gmtime 
utc_localtime 
utc_mkanytime 
utc_mkgmtime 
utc_mklocaltime 
utc_mkreltime 
utc_reltime 


utc_boundtime 
utc_spantime 
utc_pointtime 


utc_cmpintervaltime 
utc_cmpmidtime 


utc_abstime 
utc_addtime 
utc_mulftime 
utc_multime 
utc_subtime 


utc_anyzone 
utc_gmizone 
utc_localzone 
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To/From 
VMS time: 


utc_mkvmsanytime 
utc_mkvmsgmtime 
utc_mkvmslocaltime 
utc_vmsanytime 
utc_vmsgmtime 
utc_vmslocaltime 


To/From 
timespec Structures: 


utc_binreltime 
utc_bintime 

utc_mkbinreltime 
utc_mkbintime 


ZK-4986A-GE 
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An alphabetical listing of the DECdts portable interface routines and a brief 
description of each one follows: 


utc_abstime 
utc_addtime 


utc_anytime 


utc_anyzone 
utc_ascanytime 
utc_ascgmtime 
utc_asclocaltime 
utc_ascreltime 
utc_binreltime 
utc_bintime 
utc_boundtime 
utc_cmpintervaltime 
utc_cmpmidtime 
utc_gettime 
utc_getusertime 
utc_gmtime 


utc_gmtzone 
utc_localtime 


utc_localzone 
utc_mkanytime 


utc_mkascreltime 
utc_mkasctime 
utc_mkbinreltime 


utc_mkbintime 
utc_mkgmtime 


Computes the absolute value of a binary relative time. 


Computes the sum of two binary timestamps; the timestamps 
can be two relative times or a relative time and an absolute 
time. 


Converts a binary timestamp into a tm structure, using the 
TDF information contained in the timestamp to determine the 
TDF returned with the tm structure. 


Gets the time zone label and offset from GMT, using the TDF 
contained in the input utc. 


Converts a binary timestamp into an ASCII string that 
represents an arbitrary time zone. 


Converts a binary timestamp into an ASCII string that 
expresses a GMT time. 


Converts a binary timestamp to an ASCII string that 
represents a local time. 


Converts a binary timestamp that expresses a relative time to 
its ASCII representation. 


Converts a relative binary timestamp into timespec 
structures that express relative time and inaccuracy. 


Converts a binary timestamp into a timespec structure. 


Given two UTC times, one before and one after an event, 
returns a single UTC time whose inaccuracy includes the 
event. 


Compares two binary timestamps or two relative binary 
timestamps. 


Compares two binary timestamps or two relative binary 
timestamps, ignoring inaccuracies. 


Returns the current system time and inaccuracy as an opaque 
binary timestamp. 


Returns the time and process-specific TDF, rather than the 
system-specific TDF. 


Converts a binary timestamp into a tm structure that 
expresses GMT or the equivalent UTC. 


Gets the time zone label and zero offset from GMT, given utc. 


Converts a binary timestamp into a tm structure that 
expresses local time. 


Gets the time zone label and offset from GMT, given utc. 


Converts a tm structure and TDF (expressing the time in an 
arbitrary time zone) into a binary timestamp. 


Converts a null-terminated character string, which represents 
a relative timestamp to a binary timestamp. 


Converts a null-terminated character string, which represents 
an absolute timestamp, to a binary timestamp. 


Converts a timespec structure expressing a relative time toa 
binary timestamp. 


Converts a timespec structure into a binary timestamp. 


Converts a tm structure that expresses GMT or UTC toa 
binary timestamp. 
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utc_mklocaltime 
utc_mkreltime 
utc_mkvmsanytime 
utc_mkvmsgmtime 
utc_mkvmslocaltime 
utc_mulftime 


utc_multime 
utc_pointtime 


utc_reltime 


utc_spantime 


utc_subtime 


utc_vmsanytime 
utc_vmsgmtime 


utc_vmslocaltime 


9.5 DECdts API Routine Functions 


Converts a tm structure that expresses local time to a binary 
timestamp. 


Converts a tm structure that expresses relative time to a 
binary timestamp. 

Converts a binary OpenVMS format time and TDF (expressing 
the time in an arbitrary time zone) to a binary timestamp. 


Converts a binary OpenVMS format time expressing GMT (or 
the equivalent UTC) into a binary timestamp. 


Converts a local binary OpenVMS format time to a binary 
timestamp, using the host system's TDF. 


Multiplies a relative binary timestamp by a floating-point 
value. 


Multiplies a relative binary timestamp by an integer factor. 


Converts a binary timestamp to three binary timestamps that 
represent the earliest, most likely, and latest time. 


Converts a binary timestamp that expresses a relative time 
into a tm structure, 


Given two (possibly unordered) UTC timestamps, returns a 
single UTC time interval whose inaccuracy spans the two 
input timestamps. 


Computes the difference between two binary timestamps that 
express two relative times (an absolute time and a relative 
time, two relative times, or two absolute times). 


Converts a binary timestamp to a binary OpenVMS-format 
time, using the TDF contained in the binary timestamp. 


Converts a binary timestamp to a binary OpenVMS-format 
time expressing GMT or the equivalent UTC. 


Converts a binary timestamp to a local binary OpenVMS 
format time, using the host system’s time differential factor. 


Notes 


Absolute time is a point on a time scale; absolute time measurements 
are derived from system clocks or external time-providers. For DECdts, 
absolute times reference the UTC standard and include the inaccuracy 
and other information. When you display an absolute time, DE Cdts 
converts the time to ASCII text, as shown in the following display: 


1996-11-21-13:30:25.785-04:001000.082 


Relative time is a discrete time interval that is usually added to or 
subtracted from an absolute time. A time differential factor (TDF) 


associated with an absolute time is one example of a relative time Note 
that a relative time does not use the calendar date fields, because these 
fields concern absolute time. 

Coordinated Universal Time (UTC) is the international time standard 
that DECdts uses. The zero hour of UTC is based on the zero hour of 
Greenwich Mean Time (GMT). The documentation consistently refers to 
the time zone of the Greenwich Meridian as GMT. However, this time 
zone is also sometimes referred to as UTC. 

The time differential factor (TDF) is the difference between UTC and 
the time in a particular time zone. 

OpenVMS systems do not have a default time zone rule. You 

select a time zone by defining sys$timezone rule during the 
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sys$Smanager :net$configure.com procedure, or by explicitly defining 
sysStimezone_ rule. 


Unless otherwise specified, the default input and output parameters for 
the DECDts API routine commands are as follows: 


e Ifutc is not specified as an input parameter, the current time is used. 
e If inacc is not specified as an input parameter, infinity is used. 


e If no output parameter is specified, no result (or an error) is returned. 


The following command reference section includes all DECdts API routines. 
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utc_abstime 


utc_abstime 
Computes the absolute value of a relative binary timestamp. 


Format 
#include <utc.h> 
int utc_abstime(result, *utc7) 


utc_t result; 
const utc_t “utc7; 


Parameters 


Input 
utc? 
Relative binary timestamp. 


Output 
result 


Absolute value of the input relative binary timestamp. 

Description 
The Absolute Time routine computes the absolute value of a relative binary 
timestamp. The input timestamp represents a relative (delta) time. 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 


Example 


The following example scales a relative time, computes its absolute value, and 
prints the result. 


utc_t relutc, scaledutc; 
char timstr [UTC_MAX STR_LEN] ; 
/* 
* Make sure relative timestamp represents a positive interval... 
#] 
utc_abstime(&relutc, /* Out: Abs-value of rel time */ 
&relutc) ; /* In: Relative time to scale */ 
/* 
* Scale it by a factor of 17... 
*/ 
utc_multime (&scaledutc, /* Out: Scaled relative time +*/ 
&relutc, /* In: Relative time to scale */ 
17L) ; /* In: Scale factor */ 
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utc_abstime 


Out: 


In: 
In: 


Out: 


In: 
In: 


Out: 


In: 
In: 


utc_ascreltime(timstr, /* 
UTC_MAX STR LEN, /* 
&scaledutc) ; /* 
/* 
printf ("%s\n",timstr) ; 
/* 
* Scale it by a factor of 17.65... 
ay 
utc_mulftime(&scaledutc, /* 
&relutc, /* 
17.65); /* 
utc_ascreltime(timstr, /* 
UTC_MAX STR LEN, /* 
&scaledutc) ; /* 
/* 


printf ("$s\n",timstr) ; 


ASCII relative time 
Length of input string 
Relative time to 
convert 


Scaled relative time 
Relative time to scale 
Scale factor 


ASCII relative time 
Length of input string 
Relative time to 
convert 
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utc_addtime 


utc_addtime 


Computes the sum of two binary timestamps; the timestamps can be two relative 
times or a relative time and an absolute time. 


Format 
#include <utc.h> 
int utc_addtime(result, “utc7, *utc2) 


utc_t result; 
const utc_t “uic7; 
const utc_t “utc2; 


Parameters 


Input 
utc? 
Binary timestamp or relative binary timestamp. 


utc2 
Binary timestamp or relative binary timestamp. 


Output 


result 
Resulting binary timestamp or relative binary timestamp, depending on the 
operation performed: 


e redative time +rdative time = relative time 

e absolute time + rdative time = absolute time 

e redative time + absolute time = absolute time 

e absolute time + absolute time is undefined. See NOTES. 


Description 


The Add Time routine adds two binary timestamps, producing a third binary 
timestamp whose inaccuracy is the sum of the two input inaccuracies. One or 
both of the input timestamps typically represent a relative (delta) time. The TDF 
in the first input timestamp is copied to the output. 


Notes 


Although no error is returned, do not use the combination absolute time + 
absolute time 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 
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utc_addtime 


Example 


The following example shows how to compute a timestamp that represents a time 
at least 5 seconds in the future. 


utc_t now, future, fivesec; 

reltimespec_t tfivesec; 

timespec t tzero; 

/* 
* Construct a timestamp that represents 5 seconds... 
4 


tfivesec.tv_sec = 5; 
tfivesec.tv_nsec = 0; 
tzero.tv_sec = 0; 
tzero.tv_nsec = 0; 
utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */ 
&tfivesec, /* In: 5 secs in timespec */ 
&tzero); /* In: 0 secs inaccuracy in timespec */ 
/* 
* Get the maximum possible current time... 
* (NULL input parameter is used to specify the current time.) 


7) 
utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */ 
(utc_t *)0, /* Out: Midpoint of current time */ 
&now, /* Out: Latest possible current time */ 
(utc_t *)0);/* In: Use current time */ 
/* 
* Add 5 seconds to get future timestamp... 
*y 
utc_addtime (&future, /* Out: Future binary timestamp */ 
é&now, /* In: Latest possible time now */ 
&fivesec); /* In: 5 secs */ 


Related Functions 


utc_subtime 
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utc_anytime 


utc_anytime 


Format 


Parameters 


Description 


Converts a binary timestamp to a tm structure, using the time differential factor 
(TDF) information contained in the timestamp to determine the TDF returned 
with the tm structure. 


#include <utc.h> 
int utc_anytime(timeim, *ins, *inacctm, “ins, “tdf, “utc) 


struct tm timetm; 
long “ins; 

struct tm *inacctm, 
long “ins; 

long “tof, 

const utc_t “utc; 


Input 
utc 
Binary timestamp. 


Output 


timetm 
Time component of the binary timestamp expressed in the timestamp’s local time. 


tns 
Nanoseconds since time component of the binary timestamp. 


inacctm 

Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is 
finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values 
of 0. The field tm_yday contains the inaccuracy in days. If the inaccuracy is 
infinite, all tm structure fields return values of -1. 


ins 
Nanoseconds of inaccuracy component of the binary timestamp. 


tdf 
TDF component of the binary timestamp in units of seconds east or west of GMT. 


The Any Time routine converts a binary timestamp to a tm structure. The TDF 
information contained in the timestamp is returned with the time and inaccuracy 
components; the TDF component determines the offset from GMT and the local 
time value of the tm structure. Additional returns include nanoseconds since 
Time and nanoseconds of inaccuracy. 
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utc_anytime 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 


The following example converts a timestamp, using the TDF information in the 
timestamp, then prints the result. 


utc_t evnt ; 

struct tm tmevnt ; 
timespec_t tevnt, ievnt; 
char tznam[80] ; 

/* 


* Assume evnt contains the timestamp to convert... 

* 

* Get time as a tm structure, using the time zone information in 
* the timestamp... 


*/ 
utc_anytime(&tmevnt, /* Out: tm struct of time of evnt */ 
(long *)0, /* Out: nanosec of time of evnt */ 
(struct tm *)0, /* Out: tm struct of inacc of evnt */ 
(long *)0, /* Out: nanosec of inacc of evnt */ 
(int *)0, /* Out: tdf of evnt */ 
&evnt) ; /* In: binary timestamp of evnt */ 
/* 
* Get the time and inaccuracy as timespec structures... 
x) 
utc_bintime(&tevnt, /* Out: timespec of time of evnt */ 
&ievnt, /* Out: timespec of inacc of evnt */ 
(int *)0, /* Out: tdf of evnt */ 
&evnt) ; /* In: Binary timestamp of evnt */ 
/* 


* Construct the time zone name from time zone information in the 
* timestamp... 


+7 
utc_anyzone (tznam, /* Out: Time zone name */ 
80, /* In: Size of time zone name */ 
(long *)0, /* Out: tdf of event */ 
(long *)0, /* Out: Daylight saving flag */ 
&evnt) ; /* In: Binary timestamp of evnt */ 
/* 
* Print timestamp in the format: 
* 
* 1991-03-05-21:27:50.02310.140 (GMT-5:00) 
* 1992-04-02-12:37:24.003Iinf (GMT+7:00) 
* 
* 


/ 


printf ("%Sd-%02d-%02d-%02d:%02d:%02d.%03d", 
tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday, 
tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec, 
(tevnt.tv_nsec/1000000) ); 


if ((long)ievnt.tv_sec == -1) 
printf ("Iinf") ; 
else 
printf ("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000)); 
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printf(" (%s)\n", tznam) ; 


Related Functions 


utc_mkanytime, utc_anyzone, utc_gettime, utc_getusertime, utc_gmtime, 
utc_localtime 
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utc_anyzone 


utc_anyzone 


Gets the time zone label and offset from GMT, using the TDF contained in the 


input utc. 
Format 
#include <utc.h> 
int utc_anyzone(izname, izlen, *tdf, isdst, “utc) 
char tzname; 
size_t tzlen; 
long “tof, 
int *isdst; 
const utc_t “utc; 
Parameters 
Input 
tzlen 
Length of the tzname buffer. 
utc 
Binary time. 
Output 
izname 
Character string that is long enough to hold the time zone label. 
tdf 
Longword with differential in seconds east or west of GMT. 
isdst 
Integer with a value of -1, indicating that no information is supplied as to 
whether it is standard time or daylight saving time. A value of -1 is always 
returned. 
Description 
The Any Zone routine gets the time zone label and offset from GMT, using the 
TDF contained in the input utc. The label returned is always of the form GMT 
+n or GMT — n, where n is the TDF expressed in hours:minutes. (The label 
associated with an arbitrary time zone is not known; only the offset is known.) 
Notes 


All of the output parameters are optional. No value is returned and no error 
occurs if the pointer is null. 
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utc_anyzone 


Returns 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or an insufficient buffer. 


Example 
See the sample program for the utc_anytime routine. 


Related Functions 


utc_anytime, utc_gmtzone, utc_localzone 
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utc_ascanytime 


utc_ascanytime 


Format 


Parameters 


Description 


Returns 


Example 


Converts a binary timestamp to an ASCII string that represents an arbitrary 
time zone. 


#include <utc.h> 
int utc_ascanytime( “cp, stringlen, “utc) 


char *cp; 
size_t stringlen; 
const utc_t “utc; 


Input 
stringlen 
The length of the cp buffer. 


utc 
Binary timestamp. 


Output 


cp 
ASCII string that represents the time. 


The ASCII Any Time routine converts a binary timestamp to an ASCII string 
that expresses a time. The TDF component in the timestamp determines the 
local time used in the conversion. 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 


The following example converts a time to an ASCII string that expresses the time 
in the time zone where the timestamp was generated. 


utc _t evnt; 
char localTime [UTC_MAX STR_LEN] ; 
/* 


* Assuming that evnt contains the timestamp to convert, convert 
* the time to ASCII in the following format: 


* 1991-04-01-12:27:38.37-8:0012.00 
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utc_ascanytime(localtime, /* Out: Converted time */ 
UTC_MAX STR_LEN, /* In: Length of string */ 
&evnt) ; /* In: Time to convert */ 


Related Functions 


utc_ascgmtime, utc_asclocaltime 
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utc_ascgmtime 


utc_ascgmtime 
Converts a binary timestamp to an ASCII string that expresses a GMT time. 


Format 
#include <utc.h> 
int utc_ascgmtime(“cp, stringlen, “utc) 


char “cp; 
size_t stringlen; 
const utc_t “utc; 


Parameters 


Input 
stringlen 
Length of the cp buffer. 


utc 
Binary timestamp. 


Output 
cp 
ASCII string that represents the time. 


Description 
The ASCII GMT Time routine converts a binary timestamp to an ASCII string 
that expresses a time in GMT. 


Returns 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 


Example 
The following example converts the current time to GMT format. 


char gmTime[UTC_MAX STR LEN] ; 
/* 


* Convert the current time to ASCII in the following format: 
* 


bs 1991-04-01-12:27:38.3712.00 
ay 
utc_ascgmtime (gmTime, /* Out: Converted time */ 
UTC_MAX STR_LEN, /* In: Length of string */ 
(utc_t*) NULL); /* In: Time to convert */ 


/* Default is current time */ 
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Related Functions 


utc_ascanytime, utc_asclocaltime 
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utc_asclocaltime 


Converts a binary timestamp to an ASCII string that represents a local time. 


Format 
#include <utc.h> 
int utc_asclocaltime(*cp, siringlen, “utc) 
char “cp; 
size_t stringlen; 
const utc_t “utc; 
Parameters 
Input 
stringlen 
Length of the cp buffer. 
utc 
Binary timestamp. 
Output 
cp 
ASCII string that represents the time. 
Description 
The ASCII Local Time routine converts a binary timestamp to an ASCII string 
that expresses local time. 
OpenVMS systems do not have a default time zone rule. You select a time zone 
by defining sysStimezone rule during the sys$manager :net$configure.com 
procedure, or by explicitly defining sys$timezone rule. 
Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 
Example 


The following example converts the current time to local time. 


char localTime[UTC_MAX STR LEN] ; 


/* 
* Convert the current time... 
*/ 
utc_asclocaltime(localTime, /* Out: Converted time */ 
UTC_MAX STR_LEN, /* In: Length of string */ 
(utc_t*) NULL); /* In: Time to convert */ 
/* Default is current time */ 
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Related Functions 


utc_ascanytime, utc_ascgmtime 


DECdts Portable Applications Programming Interface DECdts—27 


DECdts Portable Applicatons Programming Interface 
utc_ascreltime 


utc_ascreltime 


Converts a relative binary timestamp to an ASCII string that represents the 
time. 


Format 
#include <utc.h> 
int utc_ascreltime(*cp, stringlen, “utc) 


char “cp; 
const size_t stringlen; 
const utc_t “utc; 


Parameters 


Input 


utc 
Relative binary timestamp. 


stringlen 
Length of the cp buffer. 


Output 
cp 
ASCII string that represents the time. 


Description 


The ASCII Relative Time routine converts a relative binary timestamp to an 
ASCII string that represents the time. 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 


Example 
See the sample program for the utc_abstime routine. 


Related Functions 


utc_mkascreltime 
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utc_binreltime 


Format 


Parameters 


Description 


Returns 


Example 


Converts a relative binary timestamp to two timespec structures that express 
relative time and inaccuracy. 


#include <utc.h> 
int utc_binreltime( *timesp, *inaccsp, “utc) 


reltimespec_t *timesp; 
timespec_t *inaccsp; 
const utc_t “utc; 


Input 
utc 
Relative binary timestamp. 


Output 

timesp 

Time component of the relative binary timestamp, in the form of seconds and 
nanoseconds since the base time (1970-01-01:00:00:00.0 + 00:00! 0). 


inaccsp 
Inaccuracy component of the relative binary timestamp, in the form of seconds 
and nanoseconds. 


The Binary Relative Time routine converts a relative binary timestamp to two 
timespec structures that express relative time and inaccuracy. These timespec 
structures describe a time interval. 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


The following example measures the duration of a process, then prints the 
resulting relative time and inaccuracy. 


ute t before, duration; 
reltimespec_t tduration; 
timespec_t iduration; 


* 
* Get the time before the start of the operation... 
a“ 


utc_gettime (&before) ; /* Out: Before binary timestamp */ 
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/* 

A Goc5.5 MACET 55% 

* 

* Subtract, getting the duration as a relative time. 
* 

k 


NOTE: The NULL argument is used to obtain the current time. 


+7 
utc_subtime(&duration, /* Out: Duration rel bin timestamp */ 
(utc_t *)0, /* In: After binary timestamp */ 
&before) ; /* In: Before binary timestamp */ 
/* 
* Convert the relative times to timespec structures... 
ad 
utc_binreltime(&tduration, /* Out: Duration time timespec */ 
&iduration, /* Out: Duration inacc timespec */ 
&duration); /* In: Duration rel bin timestamp */ 
/* 
* Print the duration... 
+} 
printf ("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000)); 
if ((long)iduration.tv_sec == -1) 
printf ("Iinf\n") ; 
else 


printf ("I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000)); 


Related Functions 


utc_mkbinreltime 
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utc_bintime 
Converts a binary timestamp to a timespec structure. 


Format 
#include <utc.h> 
int utc_bintime(*timesp, *inaccsp, *tdf, *utc) 


timespec_t *timesp; 
timespec_t *inaccsp; 
long “tof, 

const utc_t “utc; 


Parameters 


Input 
utc 
Binary timestamp. 


Output 

timesp 

Time component of the binary timestamp, in the form of seconds and nanoseconds 
since the base time. 


inaccsp 
Inaccuracy component of the binary timestamp, in the form of seconds and 
nanoseconds. 


tdf 
TDF component of the binary timestamp in the form of signed number of seconds 
east or west of GMT. 


Description 


The Binary Time routine converts a binary timestamp to a timespec structure. 
The TDF information contained in the timestamp is returned. 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 
See the sample program for the utc_anytime routine. 
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Related Functions 


utc_binreltime, utc_mkbintime 
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utc_boundtime 


Given two UTC times, one before and one after an event, returns a single UTC 
time whose inaccuracy includes the event. 


Format 
#include <utc.h> 


int utc_boundtime( “result, *utc1, “utc2) 


utc_t ‘result, 
const utc_t “*uic7; 
const utc_t “utc2; 


Parameters 


Input 
utc? 
Before binary timestamp or relative binary timestamp. 


utc2 
After binary timestamp or relative binary timestamp. 


Output 
result 


Spanning timestamp. 
Description 


Given two UTC times, the Bound Time routine returns a single UTC time 
whose inaccuracy bounds the two input times. This is useful for timestamping 
events; the routine gets the utc values before and after the event, then calls 
utc_boundtime to build a timestamp that includes the event. 


Notes 


The TDF in the output UTC value is copied from the utc2 input. If one or both 
input values have infinite inaccuracies, the returned time value also has an 
infinite inaccuracy and is the average of the two input values. 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid parameter order. 
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Example 


The following example records the time of an event and constructs a single 
timestamp, which includes the time of the event. Note that the utc_getusertime 
routine is called so the time zone information that is included in the timestamp 
references the user’s environment rather than the system's default time zone. 


OpenVMS systems do not have a default time zone rule. You select a time zone 
by defining sys$timezone_ rule during the sys$manager :net$configure.com 
procedure, or by explicitly defining sys$timezone rule. 


utc_t before, after, evnt; 
/* 
* Get the time before the event... 
+} 
utc_getusertime(&before); /* Out: Before binary timestamp */ 
/* 
* Get the time after the event... 
a 
utc_getusertime(&after); /* Out: After binary timestamp */ 
/* 
* Construct a single timestamp that describes the time of the 
* event... 
a 
utc_boundtime (&evnt, /* Out: Timestamp that bounds event */ 
&before, /* In: Before binary timestamp */ 
Gafter); /* In: After binary timestamp */ 


Related Functions 


utc_gettime, utc_pointtime, utc_spantime 
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utc_cmpintervaltime 
Compares two binary timestamps or two relative binary timestamps. 


Format 
#include <utc.h> 
int utc_cmpintervaltime( ‘relation, *utc1, *utc2) 
enum utc_cmptype “relation; 


const utc_t “*uic7; 
const utc_t “ufc2; 


Parameters 


Input 
utc? 
Binary timestamp or relative binary timestamp. 


utc2 
Binary timestamp or relative binary timestamp. 


Output 


relation 
Receives the result of the comparison of utcl:utc2, where the result is an 
enumerated type with one of the following values: 


* utc_equalTo 
* utc_lessThan 
* utc_greaterThan 


* utc_indeterminate 


Description 


The Compare Interval Time routine compares two binary timestamps and 
returns a flag indicating that the first time is greater than, less than, equal to, 
or overlapping with the second time. Two times overlap if the intervals (time — 
inaccuracy, time +inaccuracy) of the two times intersect. 


The input binary timestamps express two absolute or two relative times. Do 
not compare relative binary timestamps and binary timestamps. If you do, no 
meaningful results and no errors are returned. 


This routine does a temporal ordering of the time intervals. 
utcl is utc_lessThan utc2 iff 
utcl.time + utcl.inacc < utc2.time - utc2.inacc 


utcl is utc_greaterThan utc2 iff 
utcl.time - utcl.inacc > utc2.time + utc2.inacc 


utcl utc_equalTo utc2 iff 


utcl.time == utc2.time and 
utcl.inacc == 0 and 
utc2.inacc == 0 
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utcl is utc_indeterminate with respect to utc2 if the intervals 


overlap. 
Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument. 
Example 
The following example checks to see if the current time is definitely after 1:00 p.m. 
today GMT. 
struct tm tmtime, tmzero; 
enum utc_cmptype relation; 
utc_t testtime; 
/* 
* Zero the tm structure for inaccuracy... 
+f 
memset (&tmzero, 0, sizeof (tmzero) ); 
/* 
* Get the current time, mapped to a tm structure... 
* 
* NOTE: The NULL argument is used to get the current time. 
a 
utc_gmtime (&tmtime, /* Out: Current GMT time in tm struct */ 
(long *)0, /* Out: Nanoseconds of time */ 
(struct tm *)0, /* Out: Current inaccuracy in tm struct */ 
(long *)0, /* Out: Nanoseconds of inaccuracy x / 
(utc_t *)0); /* In: Current timestamp */ 
/* 
* Construct a tm structure that corresponds to 1:00 PM... 
a 


tmtime.tm_hour = 13; 


tmtime.tm_min = 0; 
tmtime.tm_sec = 0; 
/* 
* Convert to a binary timestamp... 
+} 
utc_mkgmtime(&testtime, /* Out: Binary timestamp of 1:00 PM */ 
&tmtime, /* In: 1:00 PM in tm struct */ 
0, /* In: Nanoseconds of time */ 
&tmzero, /* In: Zero inaccuracy in tm struct */ 
0); /* In: Nanoseconds of inaccuracy */ 
/* 


* Compare to the current time, noting the use of the 
* NULL argument... 


a 
utc_cmpintervaltime(&relation, /* Out: Comparison relation */ 
(utc_t *)0, /* In: Current timestamp +*/ 
&testtime) ; /* In: 1:00 PM timestamp */ 
/* 
* If it is not later - wait, print a message, etc. 
ay 


if (relation != utc_greaterThan) { 


DECdts-36 DECdis Portable Applications Programming Interface 


DECdts Portable Applicatons Programming Interface 
utc_cmpintervaltime 


/* 

* Note: It could be earlier than 1:00 PM or it could be 

* indeterminate. If indeterminate, for some applications 
* it might be worth waiting. 

‘i 


Related Functions 


utc_cmpmidtime 
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utc_cmpmidtime 


Compares two binary timestamps or two relative binary timestamps, ignoring 
inaccuracies. 


Format 
#include <utc.h> 
int utc_cmpmidtime( ‘relation, *utc1, *utc2) 
enum utc_cmptype “relation; 


const utc_t *utc7; 
const utc_t *utc2; 


Parameters 


Input 
utc1 
Binary timestamp or relative binary timestamp. 


utc2 
Binary timestamp or relative binary timestamp. 
Output 


relation 
Result of the comparison of utcl:utc2, where the result is an enumerated type 
with one of the following values: 


* utc _equalTo 
* utc _lessThan 


* utc_greaterThan 


Description 


The Compare Midpoint Times routine compares two binary timestamps and 
returns a flag indicating that the first timestamp is greater than, less than, 

or equal to the second timestamp. Inaccuracy information is ignored for this 
comparison; the input values are, therefore, equivalent to the midpoints of the 
time intervals described by the input binary timestamps. 


The input binary timestamps express two absolute or two relative times. Do 
not compare relative binary timestamps and binary timestamps. If you do, no 
meaningful results and no errors are returned. 


The following routine does a lexical ordering on the time interval midpoints. 
utcl is utc_lessThan utc2 iff 
utcl.time < utc2.time 


utcl is utc_greaterThan utc2 iff 
utcl.time > utc2.time 


utcl is utc_equalTo utc2 iff 
utcl.time == utc2.time 
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Returns 


Example 
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(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument. 


The following example checks if the current time (ignoring inaccuracies) is after 


1:00 P.M. today local time. 


struct tm tmtime, tmzero; 
enum utc_cmptype relation; 

utc _t testtime; 

/* 


* Zero the tm structure for inaccuracy... 


ap 


memset (&tmzero, 0, sizeof(tmzero) ); 


/* 


* Get the current time, mapped to a tm structure... 


* 


* NOTE: 
*/ 
utc_localtime (&tmtime, /* Out: 
(long *)0, /* Out: 
(struct tm *)0, /* Out: 
(long *)0, /* Out: 
(utc_t *)0); /* In: 
/* 


Nanoseconds of time 
Current inacc in tm struct 
Nanoseconds of inaccuracy 
Current timestamp 


* Construct a tm structure that corresponds to 1:00 P.M.... 


* 
tmtime.tm_hour = 13; 


tmtime.tm_min 
tmtime.tm_sec 


/* 


Wo 
oO oOo 


* Convert to a binary timestamp... 


aS 


utc_mklocaltime(&testtime, /* Out: Binary timestamp of 1:00 P.M. 


&tmtime, /* In: 1:00 P.M. in tm struct 

0, /* In: Nanoseconds of time 

&tmzero, /* In: Zero inaccuracy in tm struct 
0); /* In: Nanoseconds of inaccuracy 


/* 
* Compare to the current ti 
* NULL argument... 


*/ 
utc_cmpmidtime (&relation, /* 
(utc _t *)0,  /* 
&testtime);  /* 

/* 


* If the time is not later - 


*] 


e, noting the use of the 


Out: Comparison relation 
In: Current timestamp 
In: 1:00 P.M. timestamp 


wait, print a message, etc. 


if (relation != utc_greaterThan) { 
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/* It is not later then 1:00 P.M. local time. Note that 
* this depends on the setting of the user’s environment. 
zd 


} 


Related Functions 


utc_cmpintervaltime 
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utc_gettime 


Format 


Parameters 


Description 


Returns 


Example 


Returns the current system time and inaccuracy as a binary timestamp. 


#include <utc.h> 
int utc_gettime( *utc) 


utc_t “utc; 


Input 
None. 


Output 


utc 
System time as a binary timestamp. 


The Get Time routine returns the current system time and inaccuracy ina 
binary timestamp. The routine takes the TDF from the operating system's 
kernel; the TDF is specified in a system-dependent manner. 


(0) Indicates that the routine executed successfully. 
-1 Generic error that indicates the time service cannot be accessed. 


See the sample program for the utc_binreltime routine. 
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utc_getusertime 


Format 


Parameters 


Description 


Returns 


Example 


Returns the time and process-specific TDF, rather than the system-specific TDF. 


#include <utc.h> 
int utc_getusertime( *Uic) 


utc_t “utc; 


Input 
None. 


Output 


utc 
System time as a binary timestamp. 


The Get User Time routine returns the system time and inaccuracy in a 
binary timestamp. The routine takes the TDF from the user’s environment, 
which determines the time zone rule. OpenVMS systems do not have a default 
time zone rule. You select a time zone by defining sys$timezone rule during 
the sys$manager :net$configure.com procedure, or by explicitly defining 
sysStimezone_ rule. 


(0) Indicates that the routine executed successfully. 
-1 Generic error that indicates the time service cannot be accessed. 


See the sample program for the utc_boundtime routine. 


Related Functions 


utc_gettime 
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utc_gmtime 


Format 


Parameters 


Description 


Returns 


Converts a binary timestamp to a tm structure that expresses GMT or the 
equivalent UTC. 


#include <utc.h> 
int utc_gmtime(*timetm, “tns, *inacctm, “ins, *utc) 


struct tm *timetm; 
long “*tns; 

struct tm *inacctm; 
long “ins; 

const utc_t “utc; 


Input 
utc 
Binary timestamp to be converted to tm structure components. 


Output 
timetm 
Time component of the binary timestamp. 


tns 
Nanoseconds since time component of the binary timestamp. 


inacctm 

Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is 
finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values 
of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is 
infinite, all tm structure fields return values of -1. 


ins 
Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy 
is infinite, ins returns a value of -1. 


The Greenwich Mean Time (GMT) routine converts a binary timestamp to a 
tm structure that expresses GMT (or the equivalent UTC). Additional returns 
include nanoseconds since time and nanoseconds of inaccuracy. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
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Example 


See the sample program for the utc_cmpintervaltime routine. 


Related Functions 


utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime 
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utc_gmtzone 


Format 


Parameters 


Description 


Notes 


Gets the time zone label for GMT. 


#include <utc.h> 


int utc_gmizone(*tzname, izlen, *tdf, *isdst, “utc) 


char *tzname; 
size_t izlen; 
long “tof, 

int *isdst; 

const utc_t “utc; 


Input 
tzlen 
Length of buffer tzname 


utc 
Binary timestamp. This parameter is ignored. 


Output 


tzname 
Character string long enough to hold the time zone label. 


tdf 
Longword with differential in seconds east or west of GMT. A value of zero is 
always returned. 


isdst 
Integer with a value of zero, indicating that daylight saving time is not in effect. 
A value of zero is always returned. 


The Greenwich Mean Time Zone routine gets the time zone label and zero 
offset from GMT. Outputs are always tdf =O and tzname = GMT. This routine 
exists for symmetry with the Any Zone (utc_anyzone) and the Local Zone 
(utc_localzone) routines. 


All of the output parameters are optional. No value is returned and no error 
occurs if the tzname pointer is NULL. 
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Returns 
(0) Indicates that the routine executed successfully (always returned). 
Example 
The following example prints out the current time in both local time and GMT 
time. 
utc t now; 
struct tm tmlocal, tmgmt; 
long tzoffset; 
int tzdaylight ; 
char tzlocal[80], tzgmt [80] ; 
/* 
* Get the current time once, so both conversions use the same 
* time... 
*y 
utc_gettime (&now) ; 
/* 


Convert to local time, using the process TZ environment 
* variable... 


a 
utc_localtime(&tmlocal, /* Out: Local time tm structure */ 
(long *)0, /* Out: Nanosec of time */ 
(struct tm *)0, /* Out: Inaccuracy tm structure */ 
(long *)0, /* Out: Nanosec of inaccuracy */ 
&now) ; /* In: Current binary timestamp */ 

/* 


* Get the local time zone name, offset from GMT, and current 
* daylight savings flag... 


*) 
utc_localzone(tzlocal, /* Out: Local time zone name */ 
80, /* In: Length of loc time zone name */ 
&tzoffset, /* Out: Loc time zone offset in secs */ 
&tzdaylight, /* Out: Local time zone daylight flag */ 
&now) ; /* In: Current binary timestamp */ 
/* 
* Convert to GMT... 
a 
utc_gmtime (&tmgmt , /* Out: GMT tm structure */ 
(long *)0, /* Out: Nanoseconds of time */ 
(struct tm *)0, /* Out: Inaccuracy tm structure */ 
(long *)0, /* Out: Nanoseconds of inaccuracy */ 
&now) ; /* In: Current binary timestamp */ 
/* 
* Get the GMT time zone name... 
+} 
utc_gmtzone(tzgmt, /* Out: GMT time zone name */ 
80, /* In: Size of GMT time zone name 
(long *)0, /* Out: GMT time zone offset in secs */ 
(int *)0, /* Out: GMT time zone daylight flag */ 
&now) ; /* In: Current binary timestamp */ 
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/* 
* Print out times and time zone information in the following 
* format: 
* 
* 12:00:37 (EDT) = 16:00:37 (GMT) 
* EDT is -240 minutes ahead of Greenwich Mean Time. 
* Daylight savings time is in effect. 
* 
/ 


printf ("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n", 
tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal, 
tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt) ; 
printf("%s is %d minutes ahead of Greenwich Mean Time\n", 
tzlocal, tzoffset/60) ; 
if (tzdaylight != 0) 
printf ("Daylight savings time is in effect\n"); 


Related Functions 


utc_anyzone, utc_gmtime, utc_localzone 
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utc_localtime 


Format 


Parameters 


Description 


Converts a binary timestamp to a tm structure that expresses local time. 


#include <utc.h> 
int utc_localtime(*timetm, “*tns, *inacctm, “ins, “utc) 


struct tm *timetm; 
long “ins; 

struct tm *inacctm; 
long “ins; 

const utc_t “utc; 


Input 
utc 
Binary timestamp. 


Output 
timetm 
Time component of the binary timestamp, expressing local time. 


ins 
Nanoseconds since time component of the binary timestamp. 


inacctm 

Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is 
finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values 
of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is 
infinite, all tm structure fields return values of -1. 


ins 
Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy 
is infinite, ins returns a value of -1. 


The Local Time routine converts a binary timestamp to a tm structure that 
expresses local time. 


OpenVMS systems do not have a default time zone rule. You select a time zone 
by defining sys$timezone rule during the sys$manager:net$configure.com 
procedure, or by explicitly defining sys$timezone rule. 


Additional returns include nanoseconds since time and nanoseconds of inaccuracy. 
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Returns 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 
See the sample program for the utc_gmtzone routine. 


Related Functions 


utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime 
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utc_localzone 


Format 


Parameters 


Description 


Notes 


Gets the local time zone label and offset from GMT, given utc. 


#include <utc.h> 


int utc_localzone(*tzname, tzlen, *tdf, *isdst, “utc) 


char *izname; 
size_t tzlen; 
long *tdf 

int *isdst; 

const utc_t “utc; 


#include <utc.h> 


int utc_localzone(‘*tzname, tzlen, *tdf, *isdst, “utc) 


Input 
tzlen 
Length of the tzname buffer. 


utc 
Binary timestamp. 


Output 


izname 
Character string long enough to hold the time zone label. 


tdf 
Longword with differential in seconds east or west of GMT. 


isdst 
Integer with a value of zero if standard time is in effect or a value of 1 if daylight 
savings time is in effect. 


The Local Zone routine gets the local time zone label and offset from GMT, given 
utc. 


OpenVMS systems do not have a default time zone rule. You select a time zone 
by defining sysStimezone rule during the sys$manager :net$configure.com 
procedure, or by explicitly defining sys$timezone_ rule. 


All of the output parameters are optional. No value is returned and no error 
occurs if the pointer is null. 
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Returns 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or an insufficient buffer. 


Example 
See the sample program for the utc_gmtzone routine. 


Related Functions 


utc_anyzone, utc_gmtzone, utc_localtime 
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utc_mkanytime 


Converts a tm structure and TDF (expressing the time in an arbitrary time zone) 
to a binary timestamp. 


Format 
#include <utc.h> 
int utc_mkanytime(“vic, *timetm, tns, *inacctm, ins, tdf) 
utc_t “utc; 
const struct tm *timetm; 
long tns; 
const struct tm *inacctm; 
long ins; 
long tof, 
Parameters 
Input 
timetm 
A tm structure that expresses the local time; tm_wday and tm_yday are ignored on 
input. 
ins 
Nanoseconds since time component. 
inacctm 
A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If 
tm_yday is negative, the inaccuracy is considered to be infinite; tm_mday, tm_mon, 
tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored on input. 
ins 
Nanoseconds of inaccuracy component. 
tdf 
Time differential factor to use in conversion. 
Output 
utc 
Resulting binary timestamp. 
Description 


The Make Any Time routine converts a tm structure and TDF (expressing the 
time in an arbitrary time zone) to a binary timestamp. Required inputs include 
nanoseconds since time and nanoseconds of inaccuracy. 
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Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 


The following example converts a string ISO format time in an arbitrary time 
zone to a binary timestamp. This may be part of an input timestamp routine, 
although a real implementation will include range checking. 


utc_t utc; 

struct tm tmtime, tminacc; 

float tsec, isec; 

double tmp; 

long tnsec, insec; 

int i, offset, tzhour, tzmin, year, mon; 

char *string; 

/* Try to convert the string... */ 


if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dl%e", 
&year, &mon, &tmtime.tm_mday, &tmtime.tm hour, 
&tmtime.tm min, &tsec, &tzhour, &tzmin, &isec) != 9) { 


/* Try again with a negative TDF... */ 


if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e", 
&year, &mon, &tmtime.tm mday, &tmtime.tm hour, 


&tmtime.tm min, &tsec, &tzhour, &tzmin, Gisec) != 9) { 
/* ERROR */ 
exit (1); 
/* TDF is negative */ 
tzhour = -tzhour; 
tzmin = -tzmin; 
/* Fill in the fields... */ 


tmtime.tm_year = year - 1900; 
tmtime.tm_mon = --mon; 
tmtime.tm_sec = tsec; 

tnsec = (modf(tsec, &tmp)*1.0E9) ; 
offset = tzhour*3600 + tzmin*60; 
tminacc.tm_sec = isec; 

insec = (modf(isec, &tmp)*1.0E9); 


/* Convert to a binary timestamp... */ 
utc_mkanytime (&utc, /* Out: Resultant binary timestamp */ 
&tmtime, /* In: tm struct that represents input */ 
tnsec, /* In: Nanoseconds from input */ 
&tminacc, /* In: tm struct that represents inacc */ 
insec, /* In: Nanoseconds from input */ 
offset); /* In: TDF from input */ 
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Related Functions 


utc_anytime, utc_anyzone 


DECdts-54 DECdts Portable Applications Programming Interface 


DECdts Portable Applicatons Programming Interface 
utc_mkascreltime 


utc_mkascreltime 


Format 


Parameters 


Description 


Notes 


Returns 


Example 


Converts a null-terminated character string that represents a relative timestamp 
to a binary timestamp. 


#include <utc.h> 
int utc_mkascreltime( “utc, *string) 


utc_t “utc; 
char “string; 


Input 

string 

A null-terminated string that expresses a relative timestamp in its ISO format. 
Output 


utc 
Resulting binary timestamp. 


The Make ASCII Relative Time routine converts a null-terminated string, 
which represents a relative timestamp, to a binary timestamp. 


The ASCII string must be null-terminated. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 


The following example converts an ASCII relative time string to its binary 
equivalent. 


utc_t utc; 
char str [UTC_MAX STR_LEN] ; 
/* 


* Relative time of 333 days, 12 hours, 1 minute, 37.223 seconds 


* Inaccuracy of 50.22 sec. in the format: -333-12:01:37.223150.22 
*] 


(void) strepy((void *) str, 
"-333-12:01:37.223150.22"); 
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utc_mkascreltime(&utc, /* Out: Binary utc 
str); /* In: String 


Related Functions 


utc_ascreltime 
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utc_mkasctime 


Format 


Parameters 


Description 


Notes 


Returns 


Example 


Converts a null-terminated character string that represents an absolute time to a 
binary timestamp. 


#include <utc.h> 
int utc_mkasctime(“uic, *string) 


utc_t “utc; 
char “string; 


Input 

string 

A null-terminated string that expresses an absolute time 
Output 


utc 
Resulting binary timestamp. 


The Make ASCII Time routine converts a null-terminated string that represents 
an absolute time to a binary timestamp. 


The ASCII string must be null-terminated. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time parameter or invalid results. 


The following example converts an ASCII time string to its binary equivalent. 


utc_t utc; 
char str [UTC_MAX STR_LEN] ; 


July 4, 1776, 12:01:37.223 local time 
TDF of -5:00 hours 


k 
k 
k 
* Inaccuracy of 3600.32 seconds 


*] 


(void) strcepy((void *) str, 
"1776-07-04-12:01:37.223-5:00 I 3600.32"); 
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utc_mkasctime(&utc, /* Out: Binary utc 
str); /* In: String 


Related Functions 


utc_ascanytime, utc_ascgmtime, utc_asclocaltime 
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utc_mkbinreltime 
Converts a timespec structure expressing a relative time to a binary timestamp. 


Format 
#include <utc.h> 


int utc_mkbinreltime( “utc, *timesp, *inaccsp) 


utc_t “utc; 
const reltimespec_t *timesp; 
const timespec_t *inaccsp; 


Parameters 


Input 
timesp 
A reltimespec structure that expresses a relative time. 


inaccsp 
A timespec structure that expresses inaccuracy. If tv_sec is set to a value of -1, 
the inaccuracy is considered to be infinite. 


Output 


utc 
Resulting relative binary timestamp. 


Description 


The Make Binary Relative Time routine converts a timespec structure that 
expresses relative time to a binary timestamp. 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 
See the sample program for the utc_addtime routine. 


Related Functions 


utc_binreltime, utc_mkbintime 
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utc_mkbintime 


Converts a timespec structure to a binary timestamp. 


Format 
#include <utc.h> 
int utc_mkbintime( “utc, *timesp, *inaccsp) 
utc_t “utc; 
const timespec_t *timesp; 
const timespec_t *inaccsp; 
long taf, 
Parameters 
Input 
timesp 
A timespec structure that expresses time since 1970-01-01:00:00:00.0+0:00I 0. 
inaccsp 
A timespec structure that expresses inaccuracy. If tv_sec is set to a value of -1, 
the inaccuracy is considered to be infinite. 
tdf 
TDF component of the binary timestamp. 
Output 
utc 
Resulting binary timestamp. 
Description 
The Make Binary Time routine converts a timespec structure time to a binary 
timestamp. The TDF input is used as the TDF of the binary timestamp. 
Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
Example 


The following example obtains the current time from time(), converts it toa 
binary timestamp with an inaccuracy of 5.2 seconds, and specifies GMT. 


timespec t ttime, tinacc; 


utc _t utc; 

/* 
* Obtain the current time (without the inaccuracy)... 
#/ 


DECdts-60 DECdis Portable Applications Programming Interface 


DECdts Portable Applicatons Programming Interface 
utc_mkbintime 


ttime.tv_sec = time((time_t *)0); 
ttime.tv_nsec = 0; 


/* 
* Specify the inaccuracy... 
7 
tinacc.tv_sec = 5; 
tinacc.tv_nsec = 200000000; 


/* 
* Convert to a binary timestamp... 
*/ 
utc_mkbintime (&utc, /* Out: Binary timestamp */ 
&ttime, /* In: Current time in timespec */ 
&tinacc, /* In: 5.2 seconds in timespec */ 
0); /* In: TDF of GMT */ 


Related Functions 


utc_bintime, utc_mkbinreltime 
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utc_mkgmtime 


Converts a tm structure that expresses GMT or UTC toa binary timestamp. 


Format 
#include <utc.h> 
int utc_mkgmtime( “utc, *timetm, tns, *inacctm, ins) 
utc_t *uic; 
const struct tm *timetm; 
long tns; 
const struct tm *inacctm; 
long ins; 
Parameters 
Input 
timetm 
A tm structure that expresses GMT. On input, tm_wday and tm_yday are ignored. 
tns 
Nanoseconds since time component. 
inacctm 
A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. 
If tm_yday is negative, the inaccuracy is considered to be infinite. On input, 
tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored. 
ins 
Nanoseconds of inaccuracy component. 
Output 
utc 
Resulting binary timestamp. 
Description 
The Make Greenwich Mean Time routine converts a tm structure that 
expresses GMT or UTC toa binary timestamp. Additional inputs include 
nanoseconds since the last second of time and nanoseconds of inaccuracy. 
Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
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Example 


See the sample program for the utc_cmpintervaltime routine. 


Related Functions 


utc_gmtime 
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utc_mklocaltime 


Format 


Parameters 


Description 


Converts a tm structure that expresses local time to a binary timestamp. 


#include <utc.h> 


int utc_mklocaltime( “utc, *timetm, tns, *inacctm, ins) 


utc_t “utc; 

const struct tm *timetm; 
long tns; 

const struct tm *inacctm; 
long ins; 


Input 

timetm 

A tm structure that expresses the local time. On input, tm_wday and tm_yday are 
ignored. 


ins 
Nanoseconds since time component. 


inacctm 

A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. 
If tm_yday is negative, the inaccuracy is considered to be infinite. On input, 
tm_mday, tm_mon, tm wday, tm_isdst, tm_gmtoff, and tm_zone are ignored. 


ins 
Nanoseconds of inaccuracy component. 
Output 


utc 
Resulting binary timestamp. 


The Make Local Time routine converts a tm structure that expresses local time 
to a binary timestamp. 


OpenVMS systems do not have a default time zone rule. You select a time zone 
by defining sys$timezone rule during the sys$manager:net$configure.com 
procedure, or by explicitly defining sys$timezone_ rule. 


Additional inputs include nanoseconds since the last second of time and 
nanoseconds of inaccuracy. 
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Returns 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 
See the sample program for the utc_cmpmidtime routine. 


Related Functions 


utc_localtime 
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utc_mkreltime 


Format 


Parameters 


Description 


Returns 


Converts a tm structure that expresses relative time to a relative binary 
timestamp. 


#include <utc.h> 
int utc_mkreltime( “utc, *timetm, tns, *inacctm, ins) 


utc_t “utc; 

const struct tm “*timetm; 
long tns; 

const struct tm *inacctm; 
long ins; 


Input 

timetm 

A tm structure that expresses a relative time. On input, tm_wday and tm _yday are 
ignored. 


tns 
Nanoseconds since time component. 


inacctm 

A tm structure that expresses seconds of inaccuracy. If tm_yday is negative, the 
inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_year, 
tm_wday, tm_isdst, and tm zone are ignored. 


ins 
Nanoseconds of inaccuracy component. 
Output 


utc 
Resulting relative binary timestamp. 


The Make Relative Time routine converts a tm structure that expresses relative 
time to a relative binary timestamp. Additional inputs include nanoseconds since 
the last second of time and nanoseconds of inaccuracy. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
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Example 


The following example converts a string relative time in the format (1991-04-01- 
12:12:12.12112.12) to a binary timestamp. This may be part of an input relative 
timestamp routine, though a real implementation will include range checking. 


utc _t utc; 
struct tm tmtime, tminacc; 
float tsec, isec; 
double tmp; 
long tnsec, insec; 
int 1, tzhour, tzmin, year, mon; 
char *string; 
/* 
* Try to convert the string... 
* 
/ 


if(sscanf(string, "Sd-%d-%d-%d:%d:%el%e", 
&year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, 


&tmtime.tm min, &tsec, &isec) != 7) 

/* 

* ERROR... 

? 

exit (1); 

/* 

* Fill in the fields... 

‘ 
tmtime.tm_year = year - 1900; 
tmtime.tm_mon = --mon; 


tmtime.tm_sec = tsec; 
tnsec = (modf(tsec, &tmp)*1.0E9) ; 
tminacc.tm_sec = isec; 
insec = (modf(isec, &tmp)*1.0E9); 


/* 
* Convert to a binary timestamp... 
*/ 
utc_mkreltime (&utc, /* Out: Resultant binary timestamp */ 
&tmtime, /* In: tm struct that represents input */ 
tnsec, /* In: Nanoseconds from input */ 
&tminacc, /* In: tm struct that represents inacc */ 
insec) ; /* In: Nanoseconds from input */ 


Related Functions 


utc_reltime 
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utc_mkvmsanytime 


Converts a binary OpenVMS format time and TDF (expressing the time in an 
arbitrary time zone) to a binary timestamp. 


Format 
#include <utc.h> 
int utc_mkvmsanytime( “utc, *timadr, tdf) 
utc_t “utc; 
const long *timadr, 
const long fof, 
Parameters 
Input 
*timadr 
Binary OpenVMS format time. 
tdf 
Time differential factor to use in conversion. 
Output 
*utc 
Binary timestamp. 
Description 
The Make VMS Any Time routine converts a binary time in the OpenVMS 
(Smithsonian) format and an arbitrary TDF to a UTC-based binary timestamp. 
Because the input and output values are based on different time standards, any 
input representing a value after A.D. 30,000 returns an error. 
Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
Example 


The following example shows how to convert between OpenVMS format binary 
timestamps and UTC binary timestamps, while specifying the TDF for each. The 
TDF value determines the offset from GMT and the local time. 


[kK 


start example mkvmsanytime, vmsanytime 
kK / 


#include <utc.h> 
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main () 


struct utc utcTime; 
int vmsTime [2] ; 


SYSSGETTIM(vmsTime) ; /* vead the current time */ 


/* 
* convert the VMS local time to a UTC, applying a TDF of 
* -300 minutes (the timezone is -5 hours from GMT) 


+ 
if (utc_mkvmsanytime (&utcTime, vmsTime, -300) ) 
exit (1); 
/* 


* convert UTC back to VMS local time. A TDF of -300 is applied 
* to the UTC, since utcTime was constructed with that same value. 
* This effectively gives us the same VMS time value we started 
* with. 
ay 
if (utc_vmsanytime (vmsTime, &utcTime) ) 
exit (2); 


[eK 


end example 
wR KK / 


Related Functions 


Function: utc_vmsanytime 
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utc_mkvmsgmtime 


Converts a binary OpenVMS format time expressing GMT (or the equivalent 
UTC) into a binary timestamp. 
Format 
#include <utc.h> 
int utc_mkvmsgmtime(‘“uic, *timadr) 


utc_t “utc; 
const long *timadr, 


Parameters 


Input 
*timadr 
Binary OpenVMS format time representing GMT or the UTC equivalent. 


Output 
*utc 


Binary timestamp. 
Description 


The Make VMS Greenwich Mean Time routine converts an OpenVMS format 
binary time representing GMT to a binary timestamp with the equivalent UTC 
value. Since the input and output values are based on different time standards, 
any input representing a value after A.D. 30,000 returns an error. 


Returns 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 


See the sample program for the vmsgmtime routine. 


Related Functions 


Function: utc_vmsgmtime 
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utc_mkvmslocaltime 


Format 


Parameters 


Description 


Notes 


Returns 


Converts a local binary OpenVMS format time to a binary timestamp, using the 
host system's time differential factor. 


#include <utc.h> 
int utc_mkvmslocaltime( “utc, *timadr) 


const long *timadr, 
utc_t “utc; 


Input 
*timadr 
Binary OpenVMS format time expressing local time. 


Output 


*utc 
Binary timestamp expressing the system's local time. 


The Make VMS Local Time routine converts a binary OpenVMS 

format time, representing the local time of the host system, to a binary 
timestamp. The system's local time value is defined by the time zone rule 
in sys$timezone rule, which is created by the system configuration process 
sysSmanager :netSconfigure.com. 


If the routine call is made during a seasonal time zone change when the local 
time is indeterminate, an error is returned. For example, if the time zone change 
occurs at the current local time of 2:00 A.M. to a new local time of 1:00 A.m., and 
the routine is called between 1:00 A.M. and 2:00 A.m., it cannot be determined 
which TDF applies. 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument, invalid results, or invalid routine call 
during a time zone change. 
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Example 


The following example shows how to retrieve the current local time of the 
system in the binary OpenVMS format, convert the OpenVMS format time to 
a UTC-based binary timestamp (using the system’s TDF), and print an ASCII 
representation of the binary timestamp. 


[RRR KR RRR 


start example mkvmslocaltime 
Rk EK / 


include <utc.h> 
main () 
char outstring[UTC_MAX STR_LEN] ; 


struct utc utcTime; 
int vmsTime [2]; 


SYSSGETTIM (vmsTime) ; /* read current time */ 
if (utc_mkvmslocaltime(&utcTime,vmsTime)) /* convert the local time */ 
exit (1); /* vmsTime to UTC using */ 

/* the system tdf. */ 


/* convert to ISO ascii*/ 
utc_asclocaltime(outstring, UTC_MAX STR_LEN, &utcTime) ; 
/* format and print */ 
printf ("Current time=> %s\n",outstring) ; 


[kK 


end example 
wR KKK / 


Related Functions 


Function: utc_vmslocaltime 
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utc_mulftime 


Multiplies a relative binary timestamp by a floating-point value. 


Format 
#include <utc.h> 
int utc_mulftime( “result, “utc, factor) 


utc_t *result; 
const utc_t “*uic7; 
const double factor, 


Parameters 


Input 
utc? 
Relative binary timestamp. 


factor 

Real scale factor (double-precision floating-point) (G format floating-point on VAX 
systems). 

Output 

result 


Resulting relative binary timestamp. 
Description 


The Multiply a Relative Time by a Real Factor routine multiplies a relative 
binary timestamp by a floating-point value. Either or both may be negative; 
the resulting relative binary timestamp has the appropriate sign. The unsigned 
inaccuracy in the relative binary timestamp is also multiplied by the absolute 
value of the floating-point value. 


Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


Example 


The following example scales and prints a relative time. 


utc _t relutc, scaledutc; 
struct tm  sacledreltm; 

char timstr[UTC_MAX STR_LEN] ; 
/* 


* Assume relutc contains the time to scale. 
* Scale it by a factor of 17... 
*/ 
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utc_multime(&scaledutc, /* 
&relutc, /* 

17L) ; /* 
utc_ascreltime(timstr, /* 
UTC_MAX STR_LEN, /* 

&scaledutc) ; /* 


printf ("$s\n",timstr) ; 


Out: 


In: 
In: 


Out: 


In: 
In? 


Scaled rel time 
Rel time to scale 
Scale factor 


ASCII rel time 
Length of input str 
Rel time to convert 


/* 
* Scale it by a factor of 17.65... 
*y 
utc_mulftime(&scaledutc, /* Out: Scaled rel time 
&relutc, /* In: Rel time to scale 
17.65); /* In: Scale factor 
utc_ascreltime(timstr, /* Out: ASCII rel time 
UTC_MAX STR_LEN, /* In: Input str length 
&scaledutc) ; /* In: Rel time to convert 
printf ("$s\n",timstr) ; 
/* 
* Convert it to a tm structure and print it. 
a 
utc_reltime(&scaledreltm, /* Out: Scaled rel tm 
(long *)0, /* Out: Scaled rel nano-sec 
(struct tm *)0, /* Out: Scaled rel inacc tm 
(long *)0, /* Out: Scd rel inacc nanos 
&scaledutc) ; /* In: Rel time to convert 


printf ("Approximately %d days, %d hours 
scaledreltm.tm yday, scaledreltm.tm_hour, scaledreltm.tm_min) ; 


Related Functions 


utc_multime 


and %d minutes\n", 
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utc_multime 


Multiplies a relative binary timestamp by an integer factor. 


Format 
#include <utc.h> 
int utc_multime( “result, *utc1, factor 
utc_t *result; 
const utc_t “uic7; 
long factor, 
Parameters 
Input 
utc? 
Relative binary timestamp. 
factor 
Integer scale factor. 
Output 
result 
Resulting relative binary timestamp. 
Description 
The Multiply Relative Time by an Integer Factor routine multiplies a 
relative binary timestamp by an integer. Either or both may be negative; the 
resulting binary timestamp has the appropriate sign. The unsigned inaccuracy in 
the binary timestamp is also multiplied by the absolute value of the integer. 
Returns 
(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
Example 


See the sample program for the utc_mulftime routine. 


Related Functions 


utc_mulftime 
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utc_pointtime 


Format 


Parameters 


Description 


Notes 


Returns 


Converts a binary timestamp to three binary timestamps that represent the 
earliest, most likely, and latest time. 


#include <utc.h> 
int utc_pointtime(“*uiclp, *utcmp, *utchp, *utc) 


utc_t *utclp; 
utc_t *utcmp; 
utc_t “utchp; 
const utc_t “utc; 


Input 
utc 
Binary timestamp or relative binary timestamp. 


Output 

utclp 

Lowest (earliest) possible time that the input binary timestamp or shortest 
possible relative time that the relative binary timestamp can represent. 


utcmp 
Midpoint of the input binary timestamp or the midpoint of the input relative 
binary timestamp. 


utchp 
Highest (latest) possible time that the input binary timestamp or the longest 
possible relative time that the relative binary timestamp can represent. 


The Point Time routine converts a binary timestamp to three binary timestamps 
that represent the earliest, latest, and most likely (midpoint) times. If the input 


is a relative binary time, the outputs represent relative binary times. 


All outputs have zero inaccuracy. An error is returned if the input binary 
timestamp has an infinite inaccuracy. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument. 
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Example 


See the sample program for the utc_addtime routine. 


Related Functions 


utc_boundtime, utc_spantime 
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utc_reltime 


Format 


Parameters 


Description 


Returns 


Converts a relative binary timestamp to a tm structure. 


#include <utc.h> 
int utc_reltime(*timetm, *tns, *inacctm, “ins, “utc) 


struct tm *timetm; 
long *tns; 

struct tm *inacctm; 
long “ins; 

const utc_t “utc; 


Input 
utc 
Relative binary timestamp. 


Output 

timetm 

Relative time component of the relative binary timestamp. The field tm_mday 
returns a value of -1 and the fields tm_year and tm_mon return values of zero. 
The field tm_yday contains the number of days of relative time. 


ins 
Nanoseconds since time component of the relative binary timestamp. 


inacctm 

Seconds of inaccuracy component of the relative binary timestamp. If the 
inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year 
return values of zero. The field tm_yday contains the inaccuracy in days. If the 
inaccuracy is infinite, all tm structure fields return values of -1. 


ins 
Nanoseconds of inaccuracy component of the relative binary timestamp. 


The Relative Time routine converts a relative binary timestamp to a tm 
structure. Additional returns include nanoseconds since time and nanoseconds of 
inaccuracy. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
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Example 


See the sample program for the utc_mulftime routine. 


Related Functions 


utc_mkreltime 
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utc_spantime 


Given two (possibly unordered) binary timestamps, returns a single UTC time 
interval whose inaccuracy spans the two input binary timestamps. 


Format 
#include <utc.h> 
int utc_spantime( “result, *utc1, “utc2) 


utc_t ‘result, 
const utc_t *utc7; 
const utc_t *utc2; 


Parameters 


Input 

utc? 

Binary timestamp. 
utc2 

Binary timestamp. 


Output 
result 


Spanning timestamp. 
Description 


Given two binary timestamps, the Span Time routine returns a single UTC time 
interval whose inaccuracy spans the two input timestamps (that is, the interval 
resulting from the earliest possible time of either timestamp to the latest possible 
time of either timestamp). 

Notes 
The tdf in the output UTC value is copied from the utc2 input. If either input 
binary timestamp has an infinite inaccuracy, an error is returned. 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument. 
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Example 


The following example computes the earliest and latest times for an array of 10 
timestamps. 


utc _t time_array[10], testtime, earliest, latest; 
int 1; 
/* 
* Set the running timestamp to the first entry... 
ay 
testtime = time_array[0] ; 
for (i=l; i<10; i++) { 


/* 
* Compute the minimum and the maximum against the next 
* element... 


*) 
utc_spantime (&testtime, /* Out: Resultant interval */ 
&testtime, /* In: Largest previous interval */ 
&time_array[i]); /* In: Element under test x / 
/* 
* Compute the earliest possible time... 
a 
utc_pointtime(&earliest, /* Out: Earliest poss time in array */ 
(utc_t *)0, /* Out: Midpoint x / 
&latest, /* Out: Latest poss time in array */ 
&testtime) ; /* In: Spanning interval */ 


Related Functions 


utc_boundtime, utc_gettime, utc_pointtime 
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utc_subtime 


Computes the difference between two binary timestamps that express either an 
absolute time and a relative time, two relative times, or two absolute times. 


Format 
#include <utc.h> 
int utc_subtime( “result, “uic7, *utc2) 


utc_t ‘result, 
const utc_t *utc7; 
const utc_t *utc2; 


Parameters 


Input 
utc1 
Binary timestamp or relative binary timestamp. 


utc2 
Binary timestamp or relative binary timestamp. 


Output 


result 
Resulting binary timestamp or relative binary timestamp, depending on the 
operation performed: 


e absolute time — absolute time = relative time 

e rdative time — rdative time = relative time 

e absolute time — rdative time = absolute time 

e rdative time — absolute timeis undefined. See NOTES. 


Description 


The Subtract Time routine subtracts one binary timestamp from another. 
The resulting timestamp is utcl minus utc2. The inaccuracies of the two input 
timestamps are combined and included in the output timestamp. The TDF in the 
first timestamp is copied to the output. 

Notes 
Although no error is returned, do not use the combination rdiative time — 
absol ute time 


Returns 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 
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Example 


See the sample program for the utc_binreltime routine. 


Related Functions 


utc_addtime 
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utc_vmsanytime 


Format 


Parameters 


Description 


Returns 


Example 


Converts a binary timestamp to a binary OpenVMS format time The TDF 
encoded in the input timestamp determines the TDF of the output. 


#include <utc.h> 
int utc_vmsanytime( *timadr, *utc) 


const utc_t “utc; 
long *timadr, 


Input 

*utc 

Binary timestamp. 
Output 


*timadr 
Binary OpenVMS format time. 


The VMS Any Time routine converts a UTC-based binary timestamp to a 64-bit 


binary time in the OpenVMS (Smithsonian) format. Because the input and 


output values are based on different time standards, any input representing a 
value before the Smithsonian base time of November 17, 1858 returns an error. 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


See the sample program for the mkvmsanytime routine. 


Related Functions 


Function: utc_mkvmsanytime 
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utc_vmsgmtime 


Format 


Parameters 


Description 


Returns 


Example 


Converts a binary timestamp to a binary OpenVMS format time expressing GMT 
or the equivalent UTC. 


#include <utc.h> 
int utc_vmsgmtime( *timadr, “utc) 


const utc_t “utc; 
long *timaar, 


Input 
*utc 
Binary timestamp to be converted. 


Output 
*timadr 
Binary OpenVMS format time representing GMT or the UTC equivalent. 


The OpenVMS Greenwich Mean Time routine converts a UTC-based binary 
timestamp to a 64-bit binary time in the OpenVMS (Smithsonian) format. The 
OpenVMS format time represents Greenwich Mean Time or the equivalent UTC. 
Because the input and output values are based on different time standards, any 
input representing a value before the Smithsonian base time of November 17, 
1858 returns an error. 


it) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


The following example shows the following time zone and time format 
conversions: 


1. Retrieve a binary timestamp representing UTC with the sys$getutc system 
service. 


2. Convert the binary timestamp to a OpenVMS format binary time representing 
GMT 


3. Convert the OpenVMS format binary time representing GMT back toa 
UTC-based binary timestamp with a TDF of 0 (zero) 
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4. Convert the UTC-based binary time to a binary OpenVMS format time 
representing the local time; use the TDF from the system 


[kK 
start example vmsgmtime, mkvmsgmtime, vmslocaltime 
KKK / 


#include <utc.h> 


main () 

int status; 

struct utc utcTime; 
int vmsTime [2]; 


if (!((status=SYSSGETUTC (&utcTime) ) &1) ) 
exit (Status) ; /* vead curr time as a utc */ 


* convert the utcvalue into a vms time, with a timezone of 0 
* (GMT). Printing the resultant vmstime yields the time at 
* the prime meridian in Greenwich, not (necessarily) the 

* local time. 


+) 
if (utc_vmsgmtime (vmsTime, &utcTime) ) 
exit (1); 
/* 
* Convert the vmstime (which is in GMT) to a utc 
*/ 
if (utc_mkvmsgmtime (&utcTime, vmsTime) ) 
exit (2); 
/* 


* convert the UTC to local 64-bit time. Note that this is the 
* value we would have read if we had issued a 'SYSSGETTIM’ in 
* the initial statement. 
x) 
if (utc_vmslocaltime(vmsTime, &utcTime) ) 
exit (3); 


[kK 


end example 
wR KKK / 


Related Functions 


Function: utc_mkvmsgmtime 
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utc_vmslocaltime 


Format 


Parameters 


Description 


Returns 


Example 


Converts a binary timestamp to a local binary OpenVMS format time, using the 
host system's time differential factor. 


#include <utc.h> 
int utc_vmslocaltime( *timadr, “utc) 


const utc_t “utc; 
long *timaadr, 


Input 
*utc 
Binary timestamp. 


Output 
*timadr 
Binary OpenVMS format time expressing local time. 


The VMS Local Time routine converts a binary timestamp to a binary OpenVMS 
format time; the output value represents the local time of the host system. The 
system's offset from UTC and the local time value are defined by the time zone 
rule in sys$timezone rule, which is created by the system configuration process 
sysSmanager :netSconfigure.com. 


(0) Indicates that the routine executed successfully. 
-1 Indicates an invalid time argument or invalid results. 


See the sample program for the vmsgmtime routine. 


Related Functions 


Function: utc_vmsmklocaltime 
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9.6 Example Using the DECdts API Routines 


This section contains a C programming example showing a practical application 
of the DECdts API programming routines. The program performs the following 
actions: 


Prompts the user to enter time coordinates. 

Stores those coordinates in a tm structure. 

Converts the tm structure to a utc structure. 

Determines which event occurred first. 

Determines if Event 1 may have caused Event 2 by comparing the intervals. 


Prints out the utc structure in ISO text format. 


#include <time.h> /* time data structures */ 
#include <utc.h> /* ute structure definitions */ 


void ReadTime() ; 
void PrintTime(); 


/* 


* This program requests user input about events, then prints out 
* information about those events. 


wd 


main () 


{ 


struct utc eventl,event2; 

enum utc_cmptype relation; 

/* 

* Read in the two events. 
| 

ReadTime (&event1) ; 

ReadTime (&event2) ; 

/* 
* Print out the two events. 
*/ 

printf ("The first event is : "); 

PrintTime (&event1) ; 

printf ("\nThe second event is : "); 

PrintTime (&event2) ; 

printf ("\n") ; 

/* 
* Determine which event occurred first. 
*/ 

if (utc_cmpmidtime (&relation, &event1, &event2) ) 

exit (1); 
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ce relation ) 
case utc_lessThan: 
printf ("comparing midpoints: Eventl < Event2\n"); 
break; 
case utc_greaterThan: 
printf ("comparing midpoints: Eventl > Event2\n"); 
break; 
case utc_equalTo: 
printf ("comparing midpoints: Eventl == Event2\n"); 
break; 
default: 
exit (1); 
break; 


/* 

* Could Event 1 have caused Event 2? Compare the intervals. 

a7 

if (utc_cmpintervaltime (&relation, &event1, &event2) ) 
exit (1); 


‘al relation ) 
case utc_lessThan: 
printf ("comparing intervals: Eventl < Event2\n"); 
break; 
case utc_greaterThan: 
printf ("comparing intervals: Eventl > Event2\n"); 


break; 

case utc_equalTo: 

printf ("comparing intervals: Eventl == Event2\n"); 
break; 


case utc_indeterminate: 
printf ("comparing intervals: Eventl ? Event2\n"); 


default: 

exit (1); 

break; 
/* 
* Print out a utc structure in ISO text format. 
=) 


void PrintTime (utcTime) 
struct utc *tutcTime; 


char string[50]; 


/* 
* Break up the time string. 
*/ 
if (utc_ascgmtime (string, /* Out: Converted time */ 
50, /* In: String length */ 
utcTime) ) /* In: Time to convert */ 
exit (1); 
printf ("%s\n", string) ; 
} 
/* 


* Prompt the user to enter time coordinates. Store the 
* coordinates in a tm structure and then convert the 
* tm structure to a utc structure. 


a] 
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void ReadTime (utcTime) 
struct utc *utcTime; 


struct tm tmTime,tmInacc; 


void) memset ((void *)&tmTime, 0,sizeof(tmTime) ) ; 
void) memset ((void *)&tmInacc, 0,sizeof(tmInacc) ); 
void) printf ("Year? "); 

void) scanf ("%d", &tmTime.tm_year) ; 

tmTime.tm_year -= 1900; 
void) printf ("Month? "); 

void) scanf ("%d", &tmTime.tm_mon) ; 
tmTime.tm_mon -= 1; 
void) printf ("Day? "); 
void) scanf ("%d", &tmTime.tm_mday) ; 
void) printf ("Hour? "); 

void) scanf ("%d", &tmTime.tm_hour) ; 
void) printf ("Minute? "); 

void) scanf ("%d", &tmTime.tm_min) ; 
void) printf ("Inacc Secs? "); 

void) scanf ("%d", &tmInacc.tm_sec) ; 


~v 


if (utc_mkanytime(utcTime, 

&tmTime, 
(long) 0, 
& 
( 
( 


tmInacc, 
long) 0, 
long) 0) ) 


exit (1); 
} 


Assume the preceding program is named compare events.c. To compile and 
link the program on a DECnet-Plus for OpenVMS system, enter the following 
command: 


$ cc compare events.c/output=compare events.obj 
$ link compare_events.obj, sys$input:/options [Return] 
sys$library:dtss$shr.exe/share [Cirz 
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EDT Routines 


On OpenVMS operating systems, the EDT editor can be called from a program 
written in any language that generates calls using the OpenVMS Calling 
Standard. 


You can set up your call to EDT so the program handles all the editing work, or 
you can make EDT run interactively so you can edit a file while the program is 
running. 


This chapter on callable EDT assumes that you know how to call an external 
facility from the language you are using. Callable EDT is a shareable image, 
which means that you save physical memory and disk space by having all 
processes access a single copy of the image. 


10.1 Introduction to EDT Routines 


You must include a statement in your program accessing the EDT entry point. 
This reference statement is similar to a library procedure reference statement. 
The EDT entry point is referenced as EDT$EDIT. You can pass arguments 

to EDT$EDIT; for example, you can pass EDT$FILEIO or your own routine. 
When you refer to the routines you pass, call them FILEIO, WORKIO, and 
XLATE. Therefore, FILEIO can be either a routine provided by EDT (named 
EDT$FILEIO) or a routine that you write. 


10.2 Using the EDT Routines: An Example 


Example 10-1 shows a VAX BASIC program that calls EDT. All three routines 
(FILEIO, WORKIO, and XLATE) are called. Note the reference to the entry point 
EDT$EDIT in line number 500. 


Example 10-1 Using the EDT Routines in a VAX BASIC Program 


100 EXTERNAL INTEGER EDTSFILEIO 1] 
200 EXTERNAL INTEGER EDTSWORKIO 

250 EXTERNAL INTEGER AXLATE 

300 EXTERNAL INTEGER FUNCTION EDTSEDIT 
400 DECLARE INTEGER RESULT 


450 DIM INTEGER PASSFILE(1%) 
460 DIM INTEGER PASSWORK (1%) 
465 DIM INTEGER PASSXLATE (1% 
470 PASSFILE(0%) = LOC(EDTS$FILEIO) 
480 PASSWORK(0%) = LOC (EDTSWORKIO) 
485 PASSXLATE(0%) = LOC(AXLATE) 


(continued on next page) 
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Example 10-1 (Cont.) Using the EDT Routines in a VAX BASIC Program 


500 


600 


RESULT = EDTSEDIT('’FILE.BAS’,'’,’EDTINI’,'',0%, ® 
PASSFILE (0%) BY REF, PASSWORK(0%) BY REF, @ 
PASSXLATE (0%) BY REF) 
IF (RESULT AND 1%) = 0% 
THEN 

PRINT "SOMETHING WRONG" 

CALL LIBS$STOP (RESULT BY VALUE) 


900 PRINT "EVERYTHING 0.K." 

1000 END 

@ The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are 
defined so they can be passed to callable EDT. 

@ Arrays are used to construct the two-longword structure needed for data type 
BPV. 

© Here is the call to EDT. The input file is FILE.BAS, the output and journal 
files are defaulted, and the command file is EDTINI. A 0 is passed for the 
options word to get the default EDT options. 

© Thearray PASSFILE points to the entry point for all file 1/0, which is set 
up in this example to be the EDT-supplied routine with the entry point 
EDT$FILEIO. Similarly, the array PASSWORK points to the entry point 
for all work I/O, which is the EDT-supplied routine with the entry point 
EDT$WORKIO. 

© PASSXLATE points to the entry point that EDT will use for all XLATE 


processing. PASSXLATE points to a user-supplied routine with the entry 
point AXLATE. 


10.3 EDT Routines 


This section describes the individual EDT routines. 


EDT—2 EDT Routines 


EDT Routines 
EDTS$EDIT 


EDT$EDIT—Edit a File 


The EDT$EDIT routine invokes the EDT editor. 


Format 
EDT$EDIT _ in_file [,out_file] [,com_file] [,jou_file] [,options] [,fileio] [,workio] [,xlate] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
in_file 
OpenVMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor 


File specification of the input file that EDT$EDIT is to edit. The in_file argument 
is the address of a descriptor pointing to this file specification. The string that 
you enter in this calling sequence is passed to the FILEIO routine to open the 
primary input file. This is the only required argument. 


out_file 

OpenVMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


File specification of the output file that EDT$EDIT creates. The out_file 
argument is the address of a descriptor pointing to this file specification. The 
default is that the input file specification is passed to the FILEIO routine to open 
the output file for the EXIT command. 


com_file 

OpenVMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


File specification of the startup command file to be executed when EDT is 
invoked. The com_file argument is the address of a descriptor pointing to this 
file specification. The com_file string is passed to the FILEIO routine to open 
the command file. The default is the same as that for EDT command file defaults. 
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jou_file 
OpenVMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor 


File specification of the journal file to be opened when EDT is invoked. The 
jou_file argument is the address of a descriptor pointing to this file specification. 
The jou_file string is passed to the FILEIO routine to open the journal file’ The 
default is to use the same file name as in_file. 


options 

OpenVMS usage: mask_longword 
type: aligned bit string 
access: read only 
mechanism: by reference 


Bit vector specifying options for the edit operation. The options argument is the 
address of an aligned bit string containing this bit vector. Only bits <5:0> are 
currently defined; all others must be 0. The default options have all bits set to 0. 
This is the same as the default setting when you invoke EDT to edit a file from 
DCL. 


Symbols and their descriptions follow: 


Symbol Description 


EDT$M_RECOVER If set, bit <0> causes EDT to read the journal file 
and execute the commands in it, except for the 
EXIT or QUIT commands, which are ignored. After 
the journal file commands are processed, editing 
continues normally. If bit <O>is set, the FILEIO 
routine is asked to open the journal file for both input 
and output; otherwise FILEIO is asked only to open 
the journal file for output. Bit <O> corresponds to the 
/RECOVER qualifier on the EDT command line. 


EDT$M_COMMAND If set, bit <l> causes EDT to signal if the startup 
command file cannot be opened. When bit <1l> 
is 0, EDT intercepts the signal from the FILEIO 
routine indicating that the startup command file 
could not be opened. Then, EDT proceeds with 
the editing session without reading any startup 
command file. If no command file name is supplied 
with the call to the EDT$EDIT routine, EDT tries 
to open SYS$LIBRARY:EDTSYS.EDT or, if that 
fails, EDTINI.EDT. Bit <1l> corresponds to the 
/COMMAND qualifier on the EDT command line. 
If EDT$M_NOCOMMAND (bit <4>) is set, bit <1>is 
overridden because bit <4> prevents EDT from trying 
to open a command file. 

EDT$M_NOJ OURNAL If set, bit <2> prevents EDT from opening the journal 
file. Bit <2>corresponds to the /NOJ OURNAL or 
/READ_ONLY qualifier on the EDT command line. 
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Symbol Description 


EDT$M_NOOUTPUT If set, bit <3> prevents EDT from using the input 
file name as the default output file name. Bit <3> 
corresponds to the /(NOOUTPUT or /AEAD_ ONLY 
qualifier on the EDT command line. 

EDT$M_NOCOMMAND _ If set, bit <4> prevents EDT from opening a 
startup command file. Bit <4> corresponds to the 
/NOCOMMAND qualifier on the EDT command line. 

EDT$M_NOCREATE If set, bit <5> causes EDT to return to the caller if 
the input file is not found. The status returned is the 
error code EDT$_INPFILNEX. 


fileio 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 

mechanism: by reference 


User-supplied routine called by EDT to perform file 1/O functions. The fileio 
argument is the address of a bound procedure value containing the user-supplied 
routine. When you do not need to intercept any file I/O, either use the entry point 
EDT$FILEIO for this argument or omit it. When you only need to intercept some 
amount of file |/O, call the EDT$FILEIO routine for the other cases. 


To avoid confusion, note that EDT$FILEIO is a routine provided by EDT whereas 
FILEIO is a routine that you provide. 


In order to accommodate routines written in high-level languages that do up-level 
addressing, this argument must have a data type of BPV (bound procedure value). 
BPV is a two-longword entity in which the first longword contains the address 

of a procedure value and the second longword is the environment value. When 
the bound procedure is called, EDT loads the second longword into R1. If you use 
EDT$FILEIO for this argument, set the second longword to <O>. You can pass a 
<0> for the argument, and EDT will set up EDT$FILEIO as the default and set 
the environment word to 0. 


workio 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 

mechanism: by reference 


User-supplied routine called by EDT to perform I/O between the work file and 
EDT. The workio argument is the address of a bound procedure value containing 
the user-supplied routine. Work file records are addressed only by number and 
are always 512 bytes long. If you do not need to intercept work file 1/O, you can 
either use the entry point EDT$WORKIO for this argument or omit it. 


In order to accommodate routines written in high-level languages that do up-level 
addressing, this argument must have a data type of BPV (bound procedure value). 
This means that EDT loads R1 with the second longword addressed before calling 
it. If EDT$WORKIO is used for this argument, set the second longword to 0. 
You can pass a 0 for this argument, and EDT will set up EDT$WORKIO as the 
default and set the environment word to 0. 
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Description 


xlate 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 
access: function call 

mechanism: by reference 


User-supplied routine that EDT calls when it encounters the nokeypad command 
XLATE. The xlate argument is the address of a bound procedure value containing 
the user-supplied routine. The XLATE routine allows you to gain control of your 
EDT session. If you do not need control of EDT during the editing session, you 
can either use the entry point EDT$XLATE for this argument or omit it. 


In order to accommodate routines written in high-level languages that do up-level 
addressing, this argument must have a data type of BPV (bound procedure value). 
This means that EDT loads R1 with the second longword addressed before calling 
it. If EDT$XLATE is used for this argument, set the second longword to 0. You 
can pass a 0 for this argument, and EDT will set up EDT$XLATE as the default 
and set the environment word to 0. 


If the EDT session is terminated by EXIT or QUIT, the status will be a successful 
value (bit <0> =1). If the session is terminated because the file was not 

found and if the /(NOCREATE qualifier was in effect, the failure code EDT$_ 
INPFILNEX is returned. In an unsuccessful termination caused by an EDT error, 
a failure code corresponding to that error is returned. Each error status from the 
FILEIO and WORKIO routines is explained separately. 


Three of the arguments to the EDT$EDIT routine, fileio, workio, and xlate are 
the entry point names of user-supplied routines. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
EDT$ INPFILNEX /NOCREATE specified and input file does not 
exist. 


This routine also returns any condition values returned by user-supplied 
routines. 
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FILEIO 


Format 


Returns 


Arguments 


The user-supplied FILEIO routine performs file 1/O functions. Call it by 
specifying it as an argument in the EDT$EDIT routine. It cannot be called 
independently. 


FILEIO code ,stream ,record ,rhb 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


A status code that your FILE!IO routine returns to EDT$EDIT. The fileio 
argument is a longword containing the status code. The only failure code that 
is normally returned is RMS$ EOF froma GET call. All other OpenVMS RMS 
errors are signaled, not returned. The RMS signal should include the file name 
and both longwords of the RMS status. Any errors detected with the FILEIO 
routine can be indicated by setting status to an error code. That special error 
code will be returned to the program by the EDT$EDIT routine. There is a 
special status value EDT$ NONSTDFIL for nonstandard file opening. 


Condition values are returned in RO. 


code 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


A code from EDT that specifies what function the FILEIO routine is to perform. 
The code argument is the address of a longword integer containing this code. 
Following are the valid function codes: 


Function Code Description 


EDT$K_OPEN_INPUT The record argument names a file to be 
opened for input. The rhb argument is 
the default file name. 

EDT$K_OPEN OUTPUT SEQ The record argument names a file to 
be opened for output as a sequenced file. 
The rhb argument is the default file 
name. 


EDT$K_OPEN_ OUTPUT _NOSEQ The record argument names a file to be 
opened for output. The rhb argument is 
the default file name. 
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Function Code Description 


EDT$K_OPEN_IN_OUT The record argument names a file to be 
opened for both input and output. The 
rhb argument is the default file name. 


EDT$K_GET The record argument is to be filled with 
data from the next record of the file. If 
the file has record prefixes, rhb is filled 
with the record prefix. If the file has no 
record prefixes, rhb is not written. When 
you attempt to read past the end of file, 
status is set to RMS$ EOF. 


EDT$K_PUT The data in the record argument is to 
be written to the file as its next record. 
If the file has record prefixes, the record 
prefix is taken from the rhb argument. 
For a file opened for both input and 
output, EDT$K_PUT is valid only at the 
end of the file, indicating that the record 
is to be appended to the file. 

EDT$K_CLOSE_DEL The file is to be closed and then deleted. 
The record and rhb arguments are not 
used in the call. 

EDT$K_CLOSE The file is to be closed. The record and 
rhb arguments are not used in the call. 


stream 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


A code from EDT that indicates which file is being used. The stream argument 
is the address of a longword integer containing the code. Following are the valid 


codes: 

Function Code Description 

EDT$K_COMMAND FILE The command file. 

EDT$K_INPUT FILE The primary input file. 

EDT$K_INCLUDE_ FILE The secondary input file. Such a file is opened 


in response to an INCLUDE command. It is 
closed when the INCLUDE command is complete 
and will be reused for subsequent INCLUDE 
commands. 
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Function Code Description 


EDT$K_J OURNAL FILE The journal file. If bit 0 of the options is set, it 
is opened for both input and output and is read 
completely. Otherwise, it is opened for output 
only. After it is read or opened for output only, it 
is used for writing. On a successful termination 
of the editing session, the journal file is closed 
and deleted. EXIT/SAVE and QUIT/SAVE close 
the journal file without deleting it. 


EDT$K_OUTPUT FILE The primary output file. It is not opened until 
you enter the EXIT command. 
EDT$K_WRITE_FILE The secondary output file. Such a file is opened 


in response to a WRITE or PRINT command. 
It is closed when the command is complete and 
will be reused for subsequent WRITE or PRINT 


commands. 
record 
OpenVMS usage: char_string 
type: character-coded text string 
access: modify 
mechanism: by descriptor 


Text record passed by descriptor from EDT to the user-supplied FILE!IO routine; 
the code argument determines how the record argument is used. The record 
argument is the address of a descriptor pointing to this argument. When the 
code argument starts with EDT$K_OPEN, the record is a file name. When the 
code argument is EDT$K_GET, the record is a place to store the record that 
was read from the file. For code argument EDT$K_PUT, the record is a place 
to find the record to be written to the file. This argument is not used if the code 
argument starts with EDT$K_CLOSE. 


Note that for EDT$K_GET, EDT uses a dynamic or varying string descriptor; 
otherwise, EDT has no way of knowing the length of the record being read. EDT 
uses only string descriptors that can be handled by the Run-Time Library routine 
STR$COPY_DxX. 


rhb 

OpenVMS usage: char_string 

type: character-coded text string 
access: modify 

mechanism: by descriptor 


Text record passed by descriptor from EDT to the user-supplied FILE!IO routine; 
the code argument determines how the rhb argument is used. When the code 
argument starts with EDT$K_OPEN, the rhb argument is the default file name. 
When the code is EDT$K_GET and the file has record prefixes, the prefixes are 
put in this argument. When the code is EDT$K_PUT and the file has record 
prefixes, the prefixes are taken from this argument. Like the record argument, 
EDT uses a dynamic or varying string descriptor for EDT$K_GET and uses 
only string descriptors that can be handled by the Run-Time Library routine 
STR$COPY_DxX. 
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Description 


If you do not need to intercept any file |/O, you can use the entry point 
EDT$FILEIO for this argument or you can omit it. If you need to intercept 
only some file |/O, call the EDT$FILEIO routine for the other cases. 


When you use EDT$FILEIO as a value for the fileio argument, files are opened 
as follows: 


e The record argument is always the RMS file name. 
e Therhb argument is always the RMS default file name. 
e« There is no related name for the input file. 


e The related name for the output file is the input file with OFP (output file 
parse). EDT passes the input file name, the output file name, or the name 
from the EXIT command in the record argument. 


e The related name for the journal file is the input file name with the OF P 
RMS bit set. 


e The related name for the INCLUDE file is the input file name with the OFP 
set. This is unusual because the file is being opened for input. 


EDT contains support for VFC files. Normally, EDT will zero the length of the 
RHB field if the file is not a VFC file. However, when the user supplies the 
FILEIO routines, they are responsible for performing this operation. 


EDT checks for a VFC file with the following algorithm: 


IF FABSB RFM = FABSC_VFC 
AND FABSB RAT <> FABSM PRN 
THEN 
VFC file 
ELSE 
not VFC file, zero out RHB descriptor length field. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
EDT$ NONSTDFIL File is not in standard text format. 
RMS$ EOF End of file on a GET. 
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WORKIO 


Format 


Returns 


Arguments 


The user-supplied WORKIO routine is called by EDT when it needs temporary 
storage for the file being edited. Call it by specifying it as an argument in the 
EDT$EDIT routine. It cannot be called independently. 


WORKIO_ code ,recordno ,record 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by immediate value 


Longword value returned as a status code. It is generally a success code, because 
all OpenVMS RMS errors should be signaled. The signal should include the file 
name and both longwords of the RMS status. Any errors detected within work 
1/O can be indicated by setting status to an error code, which will be returned by 
the EDT$EDIT routine. 


The condition value is returned in RO. 


code 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


A code from EDT that specifies the operation to be performed. The code 
argument is the address of a longword integer containing this argument. The 
valid function codes are as follows: 


Function Code Description 


EDT$K_OPEN_IN_OUT Open the work file for both input and output. 
Neither the record nor recordno argument is 
used. 


EDT$K_GET Read a record. The recordno argument is the 
number of the record to be read. The record 
argument gives the location where the record is to 
be stored. 


EDT$K_PUT Write a record. The recordno argument is the 
number of the record to be written. The record 
argument tells the location of the record to be 
written. 


EDT$K_CLOSE_DEL Close the work file. After a successful close, the 
file is deleted. Neither the record nor recordno 
argument is used. 
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Description 


recordno 

OpenVMS usage: longword_signed 

type: longword integer (signed) 
access: read only 

mechanism: by reference 


Number of the record to be read or written. The recordno argument is the 
address of a longword integer containing this argument. EDT always writes a 
record before reading that record. This argument is not used for open or close 
calls. 


record 

OpenVMS usage: char_string 
type: character string 
access: modify 
mechanism: by descriptor 


Location of the record to be read or written. This argument always refers to a 
512-byte string during GET and PUT calls. This argument is not used for open 
or close calls. 


Work file records are addressed only by number and are always 512 bytes 
long. If you do not need to intercept work file 1/O, you can use the entry point 
EDT$WORKIO for this argument or you can omit it. 


Condition Value Returned 


SS$ NORMAL Normal successful completion. 
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XLATE 


Format 


Returns 


Argument 


Description 


The user-supplied XLATE routine is called by EDT when it encounters the 
nokeypad command XLATE. You cause it to be called by specifying it as an 
argument in the EDT$EDIT routine. It cannot be called independently. 


XLATE _ string 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword value returned as a status code. It is generally a success code. If the 
XLATE routine cannot process the passed string for some reason, it sets status 
to an error code. Returning an error code from the XLATE routine aborts the 
current key execution and displays the appropriate error message. 


The condition value is returned in RO. 


string 

OpenVMS usage: char_string 

type: character-coded text string 
access: modify 

mechanism: by descriptor 


Text string passed to the nokeypad command XLATE. You can use the nokeypad 
command XLATE by defining a key to include the following command in its 
definition: 

XLATEtext*Z 


The text is passed by the string argument. The string argument can be handled 
by the Run-Time Library routine STR$COPY_DxX. 


This argument is also a text string returned to EDT. The string is made up of 
nokeypad commands that EDT is to execute. 


The nokeypad command XLATE allows you to gain control of the EDT session. 
(See the OpenVMS EDT Reference Manual! for more information about the 
XLATE command.) If you do not need to gain control of EDT during the editing 
session, you can use the entry point EDT$XLATE for this argument or you can 
omit it. 


: ate pene! has been archived but is available on the Ope1VMS Documentation 
D-ROM. 
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Condition Value Returned 


SS$ NORMAL Normal successful completion. 
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Encryption (ENCRYPT) Routines 


The encryption routines (APIs) allow you to program encryption operations 

into applications. OpenVMS Version 8.3 164 and Alpha systems support the 
Advanced Encryption Standard (AES) algorithm, which allows any OpenVMS 
user, system manager, security manager, or programmer to secure their files, save 
sets, or application data with AES encryption. The former DES algorithm is also 
supported for complete backward compatibility. This allows updating archived 
data encrypted with DES to the more secure AES encryption algorithm. 


Note 


The DES encryption standard, reviewed and approved by the National 
Bureau of Standards (NBS) every five years, remained the popular 
standard until 1992. The Natonal Institue of Standards and Technology 
(NIST) later declared the minimum encryption standard to be TripleDES 
(or TDEA). Triple DES typically uses at least two or three different secret 
keys. Since 1999, the older single DES standard is used only for legacy 
government systems. 


Since 2001, the Advanced Encryption Standard (AES) (FIPS PUB 197[5]) 
is the approved symmetric encryption algorithm that replaced DES. 


Encryption is used to convert sensitive or otherwise private data to an 
unintelligible form called cipher text. Decryption reverses this process, taking 
the unintelligible cipher text and converting data back to its original form, called 
plaintext. Encryption and decryption are also Known as cipher and decipher. 


Note 


OpenVMS Version 8.3 integrates the former Encryption for OpenVMS 
software product into the operating system, eliminating the requirement 
for a separate installation and product license. 


11.1 Introduction to Encryption Routines 
Encryption provides the following routines, listed by function: 
e Defining, generating, and deleting keys: 
— ENCRYPT$DEFINE_ KEY 
— ENCRYPT$GENERATE_KEY 
— ENCRYPT$DELETE_KEY 
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Encrypting and decrypting files: 

— ENCRYPT$ENCRYPT 

— ENCRYPT$ENCRYPT_FILE 

— ENCRYPT$DECRYPT 

Encrypting and decrypting records: 

—- ENCRYPT$DECRYPT_ONE RECORD 
— ENCRYPT$ENCRYPT_ ONE RECORD 
Intializing and terminating the context area: 
— ENCRYPTSINIT 

— ENCRYPT$FINI 

Returning statistics: 

— ENCRYPT$STATISTICS 


11.2 AES Encryption Features 


AES encryption, like DES, is a symmetric block cipher. However, its algorithm 
is very different, its key scheduling and number of rounds are based on key size 
(10, 12, or 14 rounds for 128, 192, and 256 bit keys), making AES much stronger 
cryptographically. AES features allows any user, system manager, security 
manager, or programmer to secure their files, save sets, or application data with 
strong AES encryption. It is integrated with OpenVMS Version 8.3 and does not 
require a separate product license or installation. 


AES encryption provides the following features and compatibility: 


The DES algorithm is maintained for use with existing DES data and their 
applications. All the functions that existed with DES continue to provide that 
same level of DES support. 


AES encryption is integrated with the Backup utility (BACKUP) for 
encrypting and decrypting save sets with AES or DES. 


Command-line use of AES encryption is the same as for DES encryption, with 
minor changes to qualifiers (see the encryption routines later in this chapter). 


Changes to the ENCRYPT$ APIs are minimal, with only textual parameter or 
flag changes required to use the AES algorithm. 


AES encryption supports the AES algorithm with 4 different cipher modes. 
With each mode, you can specify a secret key in three different lengths (128, 
192, and 256 bits), for a total of 12 different cipher and decipher operations: 


— Cipher block chaining: 


AESCBC128 
AESCBC192 
AESCBC256 


— Electronic code book: 


AESECB128 
AESECB192 
AESECB256 
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— Cipher feedback: 


AESCFB128 
AESCFB192 
AESCFB256 


— Output feedback: 


AESOFB128 
AESOFB192 
AESOFB256 


The additional AES algorithm, modes, and key sizes are specified in either the 
algorithm argument to the ENCRYPT$ENCRYPT_FILE and ENCRYPTSINIT 
routines, or in the algorithm-name argument for the ENCRYPT$GENERATE _ 
KEY routine. 


AES key-length requirements. The AES key requirements are the actual 
number of bits utilized for each of the AES modes. This is actually the 
minimum number of bytes needed for the encryption or decryption operation. 
The minimum required key sizes are as follows: 


— 128-bit mode = 16-byte key 
— 192-bit mode = 24-byte key 
— 256-bit mode = 32-byte key 
For more information about encryption keys, see Section 11.3.1. 


11.2.1 AES Key, Flag Mask, and Value 


There are no new AES encryption API routines in OpenVMS Version 8.3. 
However, to accommodate the AES algorithm and the various key-length values, 
an additional AES key and AES file flag mask and value are added: 


AES key flag 


The KEY_AES mask value specified an AES key (as a longword by 
reference) to the ENCRYPT$DEFINE KEY, ENCRYPT$DELETE KEY, 
and ENCRYPT$GENERATE_KEY routines. 


— ENCRYPT$M_KEY_AES 
— ENCRYPT$V_KEY_AES 
AES file flag mask 


An additional FILE _AES flag mask (and value) is used with the 
ENCRYPT$ENCRYPT_FILE routine when encrypting files that use an 
AES algorithm. 


The ENCRYPT$ENCRYPT_FILE_FLAGS flags are used to control file 
operations such as cipher direction, file compression, and so on. The FILE_ 
AES flag controls file AES initialization and encryption operations and also 
flags AES keys. 

— ENCRYPT$M_FILE_AES 

— ENCRYPT$V_FILE AES 

The AES algorithm, mode, and key length (128, 192, or 256 bits) are 
specified in the algorithm argument for the ENCRYPT$ENCRYPT_FILE 
and ENCRYPT$INIT routines, or in the algorithm-name argument for the 


ENCRYPT$GENERATE_KEY routine. The argorithm argument is in the 
form of a character string descriptor reference (pointer), as follows: 
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— Block-mode ciphers 


AESCBC128—Cipher block chaining 
AESCBC192—Cipher block chaining 
AESCBC256—Cipher block chaining 
AESECB128—E lectronic code book 
AESECB192—E lectronic code book 
AESECB256—E lectronic code book 


—  Stream-mode ciphers 


AESCFB128—Cipher feedback 
AESCFB192—Cipher feedback 
AESCF B256—Cipher feedback 
AESOF B128—Output feedback 
AESOF B192—Output feedback 
AESOF B256—Output feedback 


Note 


AESCBC128 is the default cipher and is also used for encryption and 
decryption of the users key for storage of logical names. These ciphers are 
looked up in the order in which they are stored in their algorithm table 
with the new image file SYS$SHARE :ENCRYPT$ALG$AES.E XE file. 


11.3 How the Routines Work 


You can call the encryption routines from any language that supports the 
OpenVMS Calling Standard in 32-bit mode. After it is called, each routine does 
the following: 


e Performs its function. 


e Returns a 32-bit status code value for the calling program to determine 
success or failure. 


e Returns control to the calling program. 


The callable routines do not provide all the options of the file selection qualifiers 
available with the DCL commands ENCRYPT and DECRYPT. The functions 

of /BACKUP, /BEFORE, /BY_OWNER, /CONFIRM, /EXCLUDE, /EXPIRED, 
/SINCE, and /SHOW are supported only at the DCL level. For more information, 
see the Guide to Creating OpenVMS Modular Procedures. 


11.3.1 Encryption Keys 
This section provides information about encryptions for AES and DES. 


e AES keys are created, encrypted (always with AESCBC128 and a master 
key), and stored in a logical name table. During an encrypt operation, the key 
is fetched, decrypted, and used as a 16-, 24- or 32-byte key, depending on the 
chosen algorithm/key size for the cipher operation. 


¢ Nonliteral DES keys are compressed, that is, converted to uppercase. Only 
the characters A-Z, 0-9, dollar sign ($), period (.), and underscore (_) are 
allowed. All others are converted to spaces, and multiple spaces are removed. 
AES ASCII key values are not compressed. 
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e Use caution when creating keys to ensure they meet the minimum key length 
when later used for the algorithm/key size selected. This condition was not a 
problem with 8-byte DES keys. Any key (literal or nonliteral) that is longer 
than necessary is folded for the proper 16-, 24- or 32-byte key size. 


e The key name is a logical name for the key as stored in the logical name 
table (SYSTEM, J OB, GROUP, or PROCESS [the default]). The value can be 
ASCII (normal text keys) or hexadecimal/binary. When creating a literal key 
(key-flags =ENCRYPT$M_LITERAL_KEY), the value is stored as a literal 
value and is not compressed. 


e Errors can result when using the ENCRYPT$GENERATE_KEY routine to 
generate AES keys and specifying key lengths that are not multiples of 16. 


e Exercise care when supplying the key to the ENCRYPT$INIT routine; it 
must match the key stored in the logical name table. The descriptor type 
determines how the DES key is handled: 


— As text to be compressed, or 


-— Asa binary value not to be compressed 


AES key values are not compressed. The key flag (1 =literal, 0 = name) 
determines how the key-name argument is interpreted: 


e Asaliteral value passed directly to INIT 


e Asa key name for logical name lookup, translation, and decryption 


Note that errors can result if you use an incorrect key type. For example, 
an error occurs if the key flag argument =0 (name) and a literal key value 
is provided instead of a key name. An error can also occur if you attempt to 
provide a key name to be used as a literal value. 


For the ENCRYPTS$INIT routine, key name descriptors of type DSC$K _ 
DTYPE_T, DSC$K_DTYPE_VT, and DSC$K_DTYPE_Z specify that the key 
value be compressed for DES keys. AES key values are not compressed. 


11.3.1.1 Deleting AES Keys 


Like DES keys, AES keys are deleted or removed with the encryption command- 
line qualifier /REMOVE_KEY or with the ENCRYPT$DELETE_KEY routine: 


$ ENCRYPT/REMOVE KEY KEYNAME /AES 


The user’s secret key is encrypted with a master key and is stored in a logical 
name table (PROCESS, J OB, GROUP or SYSTEM-ENCRYP$SYSTEM table); the 
default is the PROCESS logical name table. To delete a key in a table other than 
the PROCESS logical name table, the appropriate qualifier (/) OB, /GROUP, or 
/SYSTEM) must also be specified in the ENCRYPT /REMOVE_KEY command. 


Because the user’s secret key name is unique, only one key with the same name 
can exist in the same logical name table, regardless of whether this is a DES key 
or an AES key. This means that the /AES qualifier is unnecessary, although it is 
implemented nevertheless. 
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11.3.1.2 DES Key and Data Semantics 


The National Bureau of Standards (NBS) document FIPS-PUB-46 describes the 
operation of the DES algorithm in detail. The bit-numbering conventions in the 
NBS document are different from OpenVMS numbering conventions. 


Note 


For the AES algorithm, see the National Institute of Standards and 
Technology (NIST) document FIPS-PUB-197, pages 7 through 9. 


If you are using encryption routines in conjunction with an independently 
developed DES encryption system, be sure that you are familiar with the 
relationship between the NBS and OpenVMS numbering conventions. Table 11-1 
highlights the differences. 


Table 11-1 Comparison of NBS and OpenVMS Numbering Conventions 


NBS Encryption for OpenVMS 

Numbers bits from left to right. Numbers bits from right to left. 

Displays bytes in memory from left Displays bytes in memory from right to left. 

to right. 

Handles keys and data in 8-byte Handles 8-byte blocks in OpenVMS display order. 
blocks. 

Treats keys and data as byte Treats keys and data as character strings. 
strings. 

The most significant byte is byte 1. Same. 

In DES keys, the parity bits are In DES keys, the parity bits are OpenVMS bits 0, 
DES bits 8, 16, 24, and so forth. 8, 16, and so forth. 

DES keys, when expressed as Same. 


strings of hexadecimal digits, are 
given starting with the high digit of 
byte 1, then the low digit of byte 1, 
then the high digit of byte 2, and so 
forth, through the low digit of byte 
8. 


To convert a hexadecimal key string into the 8-byte binary key, convert from 
hexadecimal to binary one byte at a time. For example, a quadword hexadecimal- 
to-binary conversion, using the library subroutine OTS$CVT_TZ_L, yields an 
incorrect, byte-reversed key. 


Note 


On OpenVMS 164 systems, AES uses an OpenVMS numbering overlay on 
FIPS-197 numbering. For a description of AES key and data semantics, 
see the National Institute of Standards and Technology (NIST) document 
FIPS-PUB-197, pages 7 through 9. 
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Figure 11-1 and Figure 11-2 compares the OpenVMS numbering overlay to the 
NBS numbering overlay. 


Figure 11-1 OpenVMS Numbering Overlay on FIPS-46 Numbering 


v4 0 15 8 23 16 31 24 (OpenVMS numbering) 
1 8 9 16 17 24 25 32 (DES numbering) 
(NBS view) 
39 32 47 40 55 48 63 56 (OpenVMS numbering) 
33 40 41 48 49 56 57 64 (DES numbering) 
ZK-8665A-GE 


Figure 11-2 NBS Numbering Overlay on an OpenVMS Quadword 


31 24 23 16 15 8 7 0 (OpenVMS numbering) 
25 32 17 24 9 16 1 8 (DES numbering) 
(OpenVMS view) 

63 56 55 48 47 40 39 32 (OpenVMS numbering) 
57 64 49 56 41 48 33 40 (DES numbering) 

ZK-8666A-GE 


11.3.2 File Encryption and Decryption 


Once a key is created, you can encrypt and decrypt files. This can be 
accomplished at the command line with the ENCRYPT and DECRYPT commands, 
or by using the ENCRYPT$ENCRYPT_FILE routine. 


File encryption encrypts RMS files in fixed-length, 512-byte records. The file 
characteristics and attributes, such as the file creation and modify date, whether 
the file was organized as sequential or indexed, and its record format (STREAM _ 
LF, VAR, or other), are preserved. You specify a key to be used for the encrypting 
a file and a data algorithm. However, the user key is used to encrypt the random 
key, initialization vector (IV), and data algorithm in the random key record. The 
random key encrypts the files attributes and feature records and its data records 
using the data algorithm that you specify. 


When decrypting the file, the key specified decrypts the random key record, which 
retrieves the random (data) key, IV, and data algorithm file. Thereafter, the file's 
attributes, feature records, and data records are decrypted with the random key, 
IV, and data algorithm from the fixed-length 512-byte records. They are then 
restored to its original format and creation date. The modified (or revised) file 
date is finally updated. 
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11.4 Maintaining Keys 


When you use AES or DES symmetric key encryption routines, first define the 
key that will be used in the encryption operation. Similarly, to decrypt a file 


specify 
keys. 


the same key. Table 11-2 describes the callable routines that maintain 


Table 11-2 Routines for Maintaining Keys 


Routine 


Description 


ENCRYPT$DEFINE_KEY Creates a key definition with a key name and a key 


value, Puts the definition into a key storage table. 


Similar to the ENCRYPT /CREATE_KEY 
command. 


ENCRYPT$DELETE_KEY Removes a key definition from a key storage 


table. Uses the key name to identify the key to 
be removed. 


Similar to the ENCRYPT /REMOVE_KEY 
command. 


ENCRYPT$GENERATE_KEY Generates random key values. 


When you call these routines, use the following arguments: 
e With ENCRYPT$DEFINE_ KEY: 


To pass the values for the key name and key value, use the key-name 
and the key-value arguments. 


To specify a key storage table, use the key-flags argument. 
To specify other key options, use the key-flags argument. 


On DES, to override key compression, use the key-flags argument. (AES 
keys are not compressed.) 


e With ENCRYPT$DELETE_KEY: 


To pass the key name, use the key-name argument. 


To specify the key storage table in which the key resides, use the 
key-flags argument. 


e With ENCRYPT$GENERATE_KEY: 


To define the length of the key, use the key-length argument in 
increments of 8 bytes for DES and 16 bytes for AES (that is, the block 
size). 


To specify the buffer into which the generated key is to be placed, use the 
key-buffer argument. 


To specify the algorithm that will use the key, use the algorithm-name 
argument. 


To optionally pass three arbitrary values for added security, use 
the factor-a, factor-b, and factor-c arguments. These values are 
randomizing factors when the routine generates a key value. For 
example, the factors might be: 


* Time an operation started 
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* Size of a certain stack 


* Copy of the last command line 


11.5 Operations on Files 


The ENCRYPT$ENCRYPT_FILE routine is similar to the DCL commands 
ENCRYPT and DECRYPT in that you use this routine with entire files. 


The ENCRYPT$ENCRYPT_FILE routine specifies the key, the input file 
specification, the output file specification, and other file operation information. 


Specify the type of operation, either encryption or decryption, with the file-flags 
argument for DES and the file-AES argument for AES operations. 


ENCRYPT$ENCRYPT_FILE does not require a prior call to ENCRYPTSINIT. 


11.6 Operations on Records and Blocks 
To operate on small records or blocks of data, use the following routines: 
e ENCRYPT$ENCRYPT_ONE_ RECORD 
* ENCRYPT$DECRYPT_ONE_RECORD 


These routines are an abbreviated form of the ENCRYPTS$INIT, 
ENCRYPT$ENCRYPT, ENCRYPT$DECRYPT, ENCRYPT$FINI sequence of 
calls. 


Do not use these routines for data that is larger than a few records. 


To use AES for one-record ciphers, an AES key must first be created and stored in 
the logical name table (encrypted). The key name of an AES key is specified as an 
address of a descriptor that contains the ASCII text for the selected AESmmmkkk 
(mode and key size) algorithm; for example, AESCBC256. Note that the input 
and output buffers (descriptor addresses) are also provided. 

11.7 Routine Descriptions 
This section describes the syntax of each callable routine. The routines are listed 
alphabetically. 

11.7.1 Specifying Arguments 


Each routine’s argument list shows the mandatory arguments first, followed 
by the optional arguments. Brackets ([ ] ) identify optional arguments in the 
argument list. 


For example, this format line shows that the required arguments are context, 
input, and output, and that the optional arguments are output-length and p1: 


ENCRYPT$DECRYPT context ,input ,output [,output-length] [,p1] 
When you specify arguments, follow these guidelines: 


e The order is important. Specify arguments in the order in which they appear 
in the argument list. 


e Separate each argument with a comma. 


e Pass a zero value for each optional argument that you omit. 
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11.7.2 Bitmasks 


Constants are associated with the symbolic names of the bitmasks 
used by the encryption routines. These constants are defined in the 
ENCRYPT STRUCTURES files that are provided with the kit. 


The examples directory, ENCRYPT$EXAMPLES, has a copy of the 
ENCRYPT STRUCTURES file in each supported programming language. 


11.7.3 Error Handling 


By default, encryption signals error conditions with messages. To intercept a 
message that is inappropriate for your application, supply a condition handler. 


For information about implementing condition handlers, see your programming 
language reference manual. 
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ENCRYPT$DECRYPT 


Format 


Arguments 


Decrypts the next record of ciphertext according to the algorithm specified in the 
ENCRYPT$INIT call. 


ENCRYPT$DECRYPT context, input, output [,output-length] [,p1] 


context 
type: longword integer (signed) 
access: write only 


mechanism: — by reference 


Context area initialized when ENCRYPT$INIT completes execution. The context 
argument is the address of a longword of unspecified interpretation that is used 
to convey context between encryption operations. 


input 
type: char_string 
access: read only 


mechanism: — by descriptor 


Ciphertext record that ENCRYPT$DECRYPT is to decrypt. The input argument 
is the address of a descriptor pointing to a byte-aligned buffer containing the 
input record to the decryption operation. 


output 
type: char_string 
access: write only 


mechanism: — by descriptor 


Plaintext record that results when ENCRYPT$DECRYPT completes execution. 
The output argument is the address of a descriptor pointing to a byte-aligned 
padding buffer that contains the output record from the decryption operation. 


If the descriptor is dynamic and insufficient space is allocated to contain the 
output record, storage is allocated from dynamic memory. If insufficient space 
exists to contain the output of the operation, then an error status is returned. 


The ENCRYPT$DECRYPT routine adjusts the length of the output descriptor, 

if possible, to reflect the actual length of the output string. If the descriptor 
type is not DSC$K_DTYPE_VS (varying string), DSC$K_DTYPE_V (varying), or 
DSC$K_DTYPE_D (dynamic), the routine takes the actual output count from the 
output-length argument. 


The output buffer must be able to accommodate a padded block to an increment 
of the block length. For AES this is 16 bytes, for DES, 8 bytes. 


output-length 

type: word integer 
access: write only 
mechanism: by reference 


Optional argument. 
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Description 


Number of bytes that ENCRYPT$DECRYPT wrote to the output buffer. The 
output-length argument is the address of a word containing the number of bytes 
written to the output buffer, including any bytes of pad characters generated by 
the selected algorithm to meet length requirements of the input buffer, if any. 
Output length does not count padding in the case of a fixed-length string. 


Some encryption algorithms have specific requirements for the length of the input 
and output strings. In particular, DESECB and DESCBC pad input data with 
from 1 to 7 bytes to form complete 64-bit blocks for operation. The values of the 
pad characters are indeterminate. 


When you decrypt fewer than 8 bytes, present the full 8 bytes resulting 

from the ENCRYPT$ENCRYPT to ENCRYPT$DECRY PT. Retain the byte 

count of the input data in order to strip trailing pad bytes after a subsequent 
decryption operation. Note that the AES block-mode algorithms (AESCBCxx and 
AESECBxxx), pad the data to even 16-byte block boundaries. For AES, 1 byte 
encrypts and decrypts to 16 bytes, 72 bytes to 80, and so forth. The AES padding 
character is a HEX number of bytes indicating the number of bytes padded, for 
example, the 1-byte encrypted pad decrypts to 15 characters of 0F following the 1 
decrypted byte of data. For the 72 bytes of data, 8 bytes of padding characters (08 
08 ... 08) follow the 72 bytes of decrypted data. DESECB and DESCBC modes 
always pad with characters of zeros. The character stream modes (AESCFB xxx, 
AE SOF Bxxx, DESCFB) do not pad the data, so the output-length matches the 
actual number of data bytes. 


p1 
type: quadword[1](DES), quadword[2](AE S) 
access: read only 


mechanism: by reference 


Optional argument. The P1 argument is the address of a quadword initialization 
vector used to seed the two modes of the DES algorithm for which it is applicable 
(DESECB and DESCFB). (That is, the DES IV initialization vector is a quadword 
reference, to an 8-byte value.) 


For AES, the optional P1 argument for the AES IV initialization vector is a 
reference to a 16-byte (2 quadword) value. 


If this argument is omitted, the initialization vector used is the residue of the 
previous use of the specified context block. ENCRYPT$INIT initializes the 
context block with an initialization vector of zero. 


The ENCRYPT$DECRYPT routine decrypts the next record of ciphertext 
according to the algorithm specified in the ENCRYPT$INIT call. Any errors 
encountered in the operation are returned as status values. The message 
authentication mode (DESMAC) is not supported by ENCRYPT$DECRY PT. 


The ENCRYPT$DECRYPT routine returns a 32-bit status code indicating the 
success or failure of the routine’s operation. 
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ENCRYPT$DECRYPT 
Condition Values Returned 
SS$ NORMAL Record successfully decrypted. 
ENCRYPT $xyz An error reported by the encryption software. 
The xyz portion identifies the message. 
SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$DECRYPT_ONE_RECORD 


Format 


Arguments 


Decrypts a small amount of data on a decrypt stream. 


Note 


To use AES for one-record ciphers, you must first create an AES key, 
which is stored in the logical name table (encrypted). The key name of 
an AES key is specified as an address of a descriptor that contains the 
ASCII text for the selected AESmmmkkk (mode and key size) algorithm, 
for example, AESCBC256. The input and output buffers (descriptor 
addresses) are also provided. 


ENCRYPT$DECRYPT_ONE_RECORD _ input, output, key-name, algorithm 


input 
type: char_string 
access: read only 


mechanism: — by descriptor 


Ciphertext record to be decrypted. The input argument is the address of a string 
descriptor pointing to a byte-aligned buffer containing the input record to be 
decrypted. 


output 
type: char_string 
access: write only 


mechanism: — by descriptor 


Plaintext record resulting when ENCRYPT$DECRYPT_ ONE RECORD completes 
execution. The output argument is the address of a string descriptor pointing to 
a byte-aligned buffer that contains the plaintext record. 


If the descriptor is dynamic and insufficient space is allocated to contain the 
output record, storage is allocated from dynamic memory. If space is insufficient 
to contain the output of the operation, an error is returned. 


The ENCRYPT$DECRYPT_ONE_RECORD routine adjusts the length of the 
output descriptor, if possible, to reflect the actual length of the output string. 


key-name 
type: char_string 
access: read only 


mechanism: — by descriptor 


Key used to initialize the decrypt stream. The key-name argument is the 
address of a string descriptor pointing to the name of the previously defined user 
key to be used. 
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algorithm 
type: char_string 
access: read only 


mechanism: — by descriptor 


Algorithm used for the decryption operation. The algorithm argument is the 
address of a string descriptor pointing to a code for the selected algorithm. The 
algorithm code is an ASCII string. Specify the descriptor type value as one of the 
following: 


e DSC$K_DTYPE_T (text) 

« DSC$K_DTYPE_VT (varying text) 

e DSC$K_DTYPE_Z (unspecified) 

For DES, the following algorithms are valid: 
e DESCBC (default) 

e DESECB 

e DESCFB 

For AES, the following algorithms are valid: 
e Cipher block chaining: 


AESCBC128 (default) 
AESCBC192 
AESCBC256 


e Electronic code book: 


AESECB128 
AESECB192 
AESECB256 


e Cipher feedback: 


AESCFB128 
AESCFB192 
AESCFB256 


¢ Output feedback: 


AESOF B128 
AESOFB192 
AESOF B256 


In some applications, only a small amount of data needs to be decrypted on a 
particular decrypt stream. The ENCRYPT$DECRYPT ONE RECORD routine 
allows you to perform such a decryption operation. 


The ENCRYPT$DECRYPT_ONE_RECORD routine is an abbreviated form of the 
ENCRYPTS$INIT, ENCRYPT$DECRYPT, and ENCRYPT$FINI sequence of calls. 
However, using ENCRYPT$DECRYPT_ ONE RECORD repeatedly to decrypt 
records of a file is extremely inefficient. 


The ENCRYPT$DECRYPT_ONE_RECORD routine returns a 32-bit status code 
indicating the success or failure of the routine’s operation. 
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Condition Values Returned 


SS$ NORMAL Operation performed. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$DEFINE_KEY 


Format 


Arguments 


Places a key definition into the process, group, job, or system key storage table. 


ENCRYPT$DEFINE_KEY key-name, key-value, key-flags 


key-name 
type: char_string 
access: read only 


mechanism: — by descriptor 


Name of the key defined when ENCRYPT$DEFINE_KEY completes execution. 
The key-name argument is the address of a string descriptor pointing toa 
char_string key that is interpreted as the name of the key to be defined. A 
maximum of 243 characters is permitted. 


Note 


Key names beginning with ENCRYPT$ are reserved for HP. 


key-value 
type: char_string 
access: read only 


mechanism: — by descriptor 


Key value defined when ENCRYPT$DEFINE_KEY completes execution. The 
key-value argument is the address of a string descriptor pointing to a vector of 
unsigned byte values that are assigned to the named key. A maximum of 240 
bytes can be assigned. 


key-flags 
type: longword 
access: read only 


mechanism: — by reference 


Flags that ENCRYPT$DEFINE KEY uses when defining a key. The key-flags 
argument is the address of a longword containing flags that control the key 
definition process. 


Each flag has a symbolic name. The constants associated with these names are 
defined in the ENCRYPT$EXAMPLES:ENCRYPT_STRUCTURES files in various 
programming languages. 


Table 11-3 defines the function of each flag. 
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Description 


Table 11-3 ENCRYPT$DEFINE_KEY Flags 


Flag Symbolic Name Function 
ENCRYPT$M_KEY_PROCESS Places definition in process table. 
ENCRYPT$M_KEY_GROUP Places definition in group table. 
ENCRYPT$M_KEY_J OB Places definition in job table. 
ENCRYPT$M_KEY_SYSTEM Places definition in system table. 
ENCRYPT$M_KEY_LITERAL Stores key without compressing. 
ENCRYPT$M_KEY_AES Designates an AES key value. 


The following AES mask can be used in addition to other flags for the key-flags 
argument (as a longword by reference). An associated AES key value can be used 
for testing the bit within the program. Use the KEY_AES key flag to specify an 
AES key: 


* ENCRYPT$M_KEY_AES 
* ENCRYPT$V_KEY_AES 


The ENCRYPT$DEFINE_KEY routine places a key definition into the process, 
group, job, or system key storage table. The key value supplied with the routine 
is processed as specified and placed in the key storage table under the indicated 
name. The ENCRYPT$DEFINE_KEY routine does not interpret the key value. 


By default, DES keys are treated as char_string keys, using the Digital 
Multinational Character Set and are compressed before being inserted into 
the key storage table. The compression proceeds as follows: 


1. The string is converted to uppercase characters. 
2. Thedigits 0 through 9 are left unchanged. 


3. All characters except letters, numerals, dollar signs, periods, and underscores 
are converted to spaces. 


4. All sequences of multiple spaces (or characters that have been converted into 
spaces) are converted into single spaces. 


When a char_string key is retrieved from key storage for use as a DES key, it is 
folded into an 8-byte key by exclusive OR-ing of 8-byte segments of the key string 
together, and then by applying odd parity to each byte by modifying the sign bit 
(bit 7). 


The key flag ENCRYPT$M_KEY_LITERAL specifies that the key string supplied 
is a binary key. A binary key is not compressed, but is placed into key storage as 
is. When a binary key is used as a DES key, it is likewise folded into an 8-byte 
key by exclusive OR-ing of 8-byte segments together. For DES, odd parity is then 
applied by modifying the low bit (bit 0) of each byte. 


AES key values are not subject to ASCII compression. Therefore, any 8-bit 
character is allowed for AES keys. 


The ENCRYPT$DEFINE_KEY routine returns a 32-bit status code indicating the 
success or failure of the routine’s operation. 
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Condition Values Returned 


SS$ NORMAL Key has been defined. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$DELETE_KEY 


Format 


Arguments 


Description 


Deletes a key definition from a key storage table. 


ENCRYPT$DELETE_KEY key-name, key-flags 


key-name 
type: char_string 
access: read only 


mechanism: — by descriptor 


Name of the key removed from a key storage table when 
ENCRYPT$DELETE_KEY completes execution. The key-name argument is 
the address of a string descriptor pointing to a char_string that is interpreted as 
the name of the key to be deleted. A maximum of 243 characters is permitted. 


key-flags 
type: longword 
access: read only 


mechanism: — by reference 


Key table from which ENCRYPT$DELETE_KEY removes a key. The key-flags 
argument is a longword containing flags that control the deletion process. The 
following flags are available: 


ENCRYPT$M_KEY_PROCESS Deletes a key from process table 
ENCRYPT$M_KEY GROUP Deletes a key from group table 
ENCRYPT$M_KEY_J OB Deletes a key from job table 
ENCRYPT$M_KEY_SYSTEM Deletes a key from system table 
ENCRYPT$M_KEY_AES Designates an AES key value 


The following AES mask can be used in addition to other flags for the key-flags 
argument (as a longword by reference). An associated AES key value can be used 
for testing the bit within the program. Use the KEY_AES key flag to specify an 
AES key: 


* ENCRYPT$M_KEY_AES 
* ENCRYPT$V_KEY_AES 


The ENCRYPT$DELETE_KEY routine deletes a key definition from a key 
storage table. The ENCRYPT$DELETE_KEY routine returns a 32-bit status code 
indicating the success or failure of the routine’s operation. 
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Condition Values Returned 


SS$ NORMAL Key has been deleted. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$ENCRYPT 


Transforms the next record of plaintext according to the algorithm you specify 
in the ENCRYPTS$INIT call. This routine performs either an encryption or 
decryption operation. 


Format 

ENCRYPT$ENCRYPT context, input, output [,output-length] [,p1] 
Arguments 

context 

type: longword integer (signed) 

access: write only 


mechanism: — by reference 


Context area initialized when ENCRYPT$INIT completes execution. The context 
argument is the address of a longword of unspecified interpretation that is used 
to convey context between encryption operations. 


input 
type: char_string 
access: read only 


mechanism: — by descriptor 


Plaintext record to encrypt. The input argument is the address of a descriptor 
pointing to a byte-aligned buffer containing the input record to the encryption 


operation. 

output 

type: char_string 

access: write only by descriptor 
mechanism: 


Ciphertext record that results when ENCRYPT$ENCRYPT completes execution. 
The output argument is the address of a descriptor pointing to a byte-aligned 
buffer that will contain the output record from the encryption operation. 


If the descriptor is dynamic and insufficient space is allocated to contain the 
output record, storage is allocated from dynamic memory. 


ENCRYPT$ENCRYPT adjusts the length of the output descriptor, if possible, to 
reflect the actual length of the output string. If the descriptor type is not DSC$K __ 
DTYPE_VS (varying string), DSC$K_DTYPE_V (varying), or DSC$K_DTYPE_D 
(dynamic), the routine takes the actual output count from the output-length 
argument. 


The output buffer must be able to accommodate a padded block to an increment 
of the block length. For AES this is 16 bytes, for DES, 8 bytes. 


output-length 

type: word integer 
access: write only 
mechanism: by reference 
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Optional argument. Number of bytes that ENCRYPT$ENCRYPT wrote to the 
output buffer. The output-length argument is the address of a word containing 
the number of bytes written to the output buffer. 


Some encryption algorithms have specific requirements for the length of the input 
and output strings. In particular, DESECB and DESCBC pad input data with 
from 1 to 7 bytes to form complete 64-bit blocks for operation. The values of the 
pad characters are indeterminate. 


When you decrypt fewer than 8 bytes, preserve and present to 
ENCRYPT$DECRYPT the full 8 bytes resulting from ENCRYPT$ENCRY PT. 
Retain the byte count of the input data in order to strip trailing pad bytes after a 
subsequent decryption operation. 


Note that the AES block-mode algorithms (AESCBCxxx and AESECBxxx) pad 
the data to even 16-byte block boundaries. For AES, one byte encrypts and 
decrypts to 16 bytes, 72 bytes to 80, and so forth. The AES padding character 

is a hexadeciman number of bytes indicating the number of bytes padded. For 
example, the 1-byte encrypted pad would decrypt to 15 characters of OF following 
the one encrypted byte of data. For the 72 bytes of data, 8 bytes of padding 
characters (08 08 ... 08) follow the 72 bytes of encrypted data. DESECB and 
DESCBC modes always pad with characters of zeros. The character stream 
modes (AESCF Bxxx, AESOF Bxxx, DESCFB). In order that the output-length 
matchs the actual number of data bytes, do not pad the data. 


p1 
type: quadword[1] (DES), quadword[2] (AES) 
access: read only 


mechanism: — by reference 


Optional argument. The P1 argument is the address of a quadword initialization 
vector used to seed the three modes (DESECB, DESCFB, and DESMAC) of the 
DES algorithm for which it is applicable. The DES IV initialization vector is a 
quadword reference, to an 8-byte value. 


For AES, the optional P1 argument for the AES IV initialization vector is a 
reference to a 16-byte (2 quadword) value. 


If you omit this argument, the initialization vector used is the residue of the 
previous use of the specified context block. ENCRYPT$INIT initializes the 
context block with an initialization vector of zero. 


The ENCRYPT$ENCRYPT routine transforms the next record of plaintext 
according to the algorithm specified in the ENCRYPTS$INIT call. Any 

errors encountered in the operation are returned as status values. The 
ENCRYPT$ENCRYPT routine returns a 32-bit status code indicating the success 
or failure of the routine’s operation. 
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Condition Values Returned 


SS$ NORMAL Record successfully encrypted. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$ENCRYPT_FILE 


Format 


Arguments 


Encrypts or decrypts data files. 


ENCRYPT$ENCRYPT_FILE  input-file, output-file, key-name, algorithm, file-flags 
[,item-list] 


input-file 
type: char_string 
access: read only 


mechanism: — by descriptor 


Name of the input file that ENCRYPT$ENCRYPT_FILE is to process. The input- 
file argument is the address of a string descriptor pointing to the file specification 
string for the input file. 


Wildcard characters are valid. To specify multiple input files, you must use 
wildcard characters. 


output-file 
type: char_string 
access: read only 


mechanism: — by descriptor 


Name of the output file that ENCRYPT$ENCRYPT_FILE is to generate. The 
output-file argument is the address of a string descriptor pointing to the file 
specification for the output file to be processed. 


You can use wildcard characters. To specify the same names for the output and 
input files, use a null character as the output-file argument. 


key-name 
type: char_string 
access: read only 


mechanism: — by descriptor 


Name of the key used when ENCRYPT$ENCRYPT_FILE processes files. The 
key-name argument is the address of a string descriptor pointing to the name of 
the key to be used in initializing the encrypt or decrypt stream used for each file 
processed. 


algorithm 
type: char_string 
access: read only 


mechanism: — by descriptor 


Name of the algorithm that ENCRYPT$ENCRYPT_FILE uses to initialize the 
process stream. The algorithm argument is the address of a string descriptor 
pointing to the name of the algorithm. 
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For DES, the following algorithms are valid: 
e DESCBC (default) 

e DESECB 

e DESCFB 

For AES, the following algorithms are valid: 
e Cipher block chaining: 


AESCBC128 (default) 
AESCBC192 
AESCBC256 


e Electronic code book: 


AESECB128 
AESECB192 
AESECB256 


¢ Cipher feedback: 


AESCFB128 
AESCFB192 
AESCFB256 


¢ Output feedback: 


AESOFB128 
AESOFB192 
AESOFB256 


file-flags 

type: longword 
access: read only 
mechanism: — by reference 


Flags that specify how ENCRYPT$ENCRYPT_FILE performs the file operation. 
The file-flags argument is the address of a longword containing a mask of flags. 
Table 11-4 shows the function of each flag. 


Table 11-4 ENCRYPT$ENCRYPT_FILE Flags 


Flag Function 
ENCRYPT$M_FILE COMPRESS Compresses file data before encryption. 
ENCRYPT$M_FILE_ENCRYPT Flag set: Encrypts the file. 
Flag clear: Decrypts the file. 
ENCRYPT$M_FILE_DELETE Deletes the input file when the operation 
completes. 
ENCRYPT$M_FILE_ERASE Erases the file with the security data 


pattern before deleting it. 
(continued on next page) 
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Table 11-4 (Cont.) ENCRYPT$ENCRYPT_FILE Flags 


Flag Function 


ENCRYPT$M_FILE_KEY_VALUE Flag set: Treats the key value as a literal 
value and does not compress it. 


Flag clear: Treats the key value as a 
text string that can be compressed. 


If the key-name argument is present, 

this flag is ignored. 
ENCRYPT$M_FILE_AES Flag set: Encrypts a file with an AES key 

and algorithm 


An additional FILE _AES flag mask (and value) is used with the 
ENCRYPT$ENCRYPT_FILE routine when encrypting files using an AES 
algorithm. The ENCRYPT$ENCRYPT_FILE_FLAGS are used to control file 
operations such as cipher direction, file compression and so on. The FILE_AES 
flag controls file AES initialization and cipher operation. 


item-list 
type: item_list_3 
access: read only 


mechanism: — by descriptor 


The optional item-list argument is used to override the data algorithm argument. 
This argument substitutes one algorithm for another that is similar in function 
but that may be different in its name. In other words, it overrides the name 

of the algorithm that is found in the random key record with the name of the 
algorithm you provided in the override descriptor. This process provides a way 
to open files that were encrypted with an algorithm name that may be different 
than the algorithm name in the decrypt environment. 


ENCRYPT$K_DATA_ALGORITHM 
type: 3 longwords 
access: read only 
mechanism: — by descriptor 


Algorithm to be used to encrypt the file. This argument specifies the address and 
length of the name string of the algorithm. 


For DES, the following algorithms are valid: 
e DESCBC (default) 

e DESECB 

e DESCFB 
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For AES, the following algorithms are valid: 
e Cipher block chaining: 


AESCBC128 (default) 
AESCBC192 
AESCBC256 


e Electronic code book: 


AESECB128 
AESECB192 
AESECB256 


¢« Cipher feedback: 


AESCFB128 
AESCFB192 
AESCFB256 


¢ Output feedback: 


AESOFB128 
AESOFB192 
AESOFB256 


Description 


The ENCRYPT$ENCRYPT FILE routine either encrypts or decrypts data files 
from within an application. 


The routine uses the user key and the specified algorithm to protect only the 
randomly generated key and the initialization vector that are used with the 
DESCBC algorithm to encrypt the file. 


The ENCRYPT$ENCRYPT_FILE routine returns a 32-bit status code indicating 
the success or failure of the routine’s operation. 


When you use this routine, do not also use ENCRYPT$INIT or ENCRYPTS$FINI. 


Condition Values Returned 


SS$ NORMAL Record successfully encrypted. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$ENCRYPT_ONE_RECORD 


Format 


Arguments 


Encrypts a small amount of data in an encryption stream. 


Note 


To use AES for 1 record ciphers, you must first create an AES key, which 
is stored in the logical name table (encrypted). The key name of an AES 
key is specified as an address of a descriptor that contains the ASCII text 
for the selected AESmmmkkk (mode and key size) algorithm, for example, 
AESCBC256. The input and output buffers (descriptor addresses) are also 
provided. 


ENCRYPT$ENCRYPT_ONE_ RECORD input, output, key-name, algorithm 


input 
type: char_string 
access: read only 


mechanism: — by descriptor 


Plaintext record to be encrypted. The input argument is the address of a string 
descriptor pointing to a byte-aligned buffer containing the input record to be 
encrypted. 


output 
type: char_string 
access: write only 


mechanism: — by descriptor 


Ciphertext record resulting when the routine completes execution. The output 
argument is the address of a string descriptor pointing to a byte-aligned buffer 
that contains the ciphertext record. 


If the descriptor is dynamic, and insufficient space is allocated to contain the 
output record, storage is allocated from dynamic memory. If insufficient space 
exists to contain the output of the operation, an error is returned. 


The ENCRYPT$ENCRYPT_ONE_RECORD routine adjusts the length of the 
output descriptor, if possible, to reflect the actual length of the output string. 


key-name 
type: char_string 
access: read only 


mechanism: — by descriptor 


Key used to initialize the encryption stream. The key-name argument is the 
address of a string descriptor pointing to the name of the previously defined user 
key to be used. 
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algorithm 
type: char_string 
access: read only 


mechanism: — by descriptor 


Algorithm used for the encryption operation. The algorithm argument is the 
address of a string descriptor pointing to a code for the selected algorithm. The 
algorithm code is an ASCII string. For descriptor type value, use one of the 
following: 


e DSC$K_DTYPE_T (text) 

e DSC$K_DTYPE_VT (varying text) 

e DSC$K_DTYPE_Z (unspecified) 

For DES, the following algorithms are valid: 
e DESCBC (default) 

« DESECB 

e DESCFB 

For AES, the following algorithms are valid: 
e Cipher block chaining: 


AESCBC128 (default) 
AESCBC192 
AESCBC256 


e Electronic code book: 


AESECB128 
AESECB192 
AESECB256 


¢ Cipher feedback: 


AESCFB128 
AESCFB192 
AESCFB256 


¢ Output feedback: 


AESOFB128 
AESOFB192 
AESOFB256 


Description 


To encrypt only a small amount of data, use the ENCRYPT$ENCRYPT ONE _ 
RECORD routine. 


The ENCRYPT$ENCRYPT_ONE_ RECORD routine is a shorthand form of the 
ENCRYPTSINIT, ENCRYPT$ENCRYPT, and ENCRYPT$FINI sequence of calls. 
However, using ENCRYPT$ENCRYPT_ONE_ RECORD repeatedly to encrypt 
records of a file is extremely inefficient. 


The ENCRYPT$ENCRYPT_ONE_RECORD routine returns a 32-bit status code 
indicating the success or failure of the routine’s operation. 
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Condition Values Returned 


SS$ NORMAL Operation performed. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$FINI 


Format 


Arguments 


Description 


Disassociates the encryption context and releases it. 


ENCRYPTS$FINI context 


context 
type: longword integer (signed) 
access: read/write 


mechanism: — by reference 


Context area terminated when ENCRYPT$FINI completes execution. The 
context argument is the address of a longword initialized by the ENCRYPT$INIT 
routine. 


The ENCRYPT$FINI routine disassociates the indicated encryption context and 
releases it. The ENCRYPT$FINI routine returns a 32-bit status code indicating 
the success or failure of the routine’s operation. 


Condition Values Returned 


SS$ NORMAL Encryption context successfully terminated. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPT$GENERATE_KEY 


Format 


Arguments 


Generates a random key value. 


ENCRYPT$GENERATE_KEY algorithm-name, key-length [,factor-a] [,factor-b] 
[,factor-c] [,key buffer] 


algorithm-name 

type: char_string 
access: read only 
mechanism: — by descriptor 


The name of the algorithm that uses the generated key. 


key-length 
type: word unsigned 
access: read only 


mechanism: — by reference 


Unsigned integer indicating the size of the key to be generated. The key-length 
argument is the address of an unsigned word containing a value that indicates 
the length of the key. 


For AES, the key-length argument takes values as increments of AES block size: 
16 bytes, 32, bytes, and 48 bytes, and so on. 


factor-a, factor-b, factor-c 
type: char_string 
access: read only 
mechanism: — by descriptor 


Optional arguments. The factor-a, factor-b, and factor-c arguments are 
operation-dependent data used as randomizing factors when the routine generates 
a key value. For example, the factors might include: 


e Timean operation started 
e Size of a certain stack 


¢ Copy of the last command line 


key-buffer 
type: char_string 
access: write 


mechanism: — by descriptor 


Buffer into which the generated key is to be placed. The key-buffer argument is 
the address of a string descriptor referencing the appropriate buffer. 


If you specify a class D descriptor, dynamic memory is allocated to contain the 
entire key. 
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Description 


The ENCRYPT$GENERATE_KEY routine generates a random key value. The 
ENCRYPT$GENERATE_KEY routine returns a 32-bit status code indicating the 
success or failure of the routine’s operation. 


Condition Values Returned 


SS$ NORMAL Key has been created. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPTSINIT 


Format 


Arguments 


Initializes the context for the encryption operation. 


ENCRYPTS$INIT context, algorithm, key-type, key-name [,p1] 


context 
type: longword integer signed 
access: write only 


mechanism: by reference 


Context area that is initialized. The context argument is the address of a 
longword of unspecified interpretation that is used to convey context between 
encryption operations. An uninitialized context longword is defined to be zero and 
is initialized to nonzero by this routine. The context area itself is allocated from 
process dynamic memory. 


algorithm 
type: char_string 
access: read/write 


mechanism: — by descriptor 


Algorithm used for the encryption operation. The algorithm argument is the 
address of a string descriptor pointing to a code for the selected algorithm. The 
algorithm code is an ASCII string. For descriptor type value, use one of the 
following: 


DSC$K_DTYPE_T (text) 
DSC$K_DTYPE_VT (varying text) 
DSC$K_DTYPE_Z (unspecified) 


For DES, the following algorithms are valid: 
e DESCBC (default) 

e DESECB 

e DESCFB 

For AES, the following algorithms are valid: 
e Cipher block chaining: 


AESCBC128 (default) 
AESCBC192 
AESCBC256 


e Electronic code book: 


AESECB128 
AESECB192 
AESECB256 
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¢ Cipher feedback: 


AESCFB128 
AESCFB192 
AESCFB256 


¢ Output feedback: 


AESOFB128 
AESOFB192 
AESOFB256 


key-type 

type: longword logical unsigned 
access: read only 

mechanism: by reference 


Code specifying how ENCRYPT$INIT is to interpret the key-name argument. 
The key-type argument is the address of an unsigned longword indicating 
whether key-name is the name of the key or the key value. If you specify: 


Key-type as 0 ENCRYPTSINIT interprets key-name as a 
descriptor pointing to the key name string. 

Key-type as 1 ENCRYPT$INIT interprets key-name as the 
descriptor for the value of the key to be used. 

key-name 

type: char_string 

access: read only 


mechanism: — by descriptor 


Key that ENCRYPT$INIT passes to the selected encryption routine. The key- 
name argument is the address of a character string descriptor containing 
the name of the key or the address of the actual key value. ENCRYPT$INIT 
interprets this argument based on the key-type value. Argument options: 


The key name Actual key value is retrieved from key storage by 
the selected encryption routine. 
A key value It is stored with a temporary name, which is passed 


to the selected encryption routine 


If the key-name argument is used to specify a key value (that is, if key-type has 
been specified as 1), the key-name string-descriptor type field determines whether 
the key value is to be treated as a char_string key or as a binary value to be used 
exactly as specified. 


If the descriptor type is DSC$K_DTYPE_T (char_string), DSC$K_DTYPE_VT 
(varying char_string), or DSC$K_DTYPE_Z (unspecified), the value is treated as 
a text string to be compressed for DES key values. ASCII compression converts 
lowercase characters to uppercase; only the characters A-Z, 0-9, dollar sign ($), 
period (.), and underscore (_) are allowed. Other characters are converted to 
Spaces, and the extra spaces are removed. AES ASCII key values are not subject 
to ASCII compression, allowing any 8-bit ASCII character. 


All other descriptor types are treated as though the key value is to be used 
exactly as specified. 
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Note 


The key name descriptors of type DSC$K_DTYPE_T, DSC$K_DTYPE_ 
VT, and DSC$K_DTYPE_Z all specify that the key value should be 
compressed. For OpenVMS Version 8.3, this functionality applies only to 
DES, not to AES. AES keys are not compressed. 


p1 
type: quadword[1] (DES), quadword[2] (AES) 
access: read only 


mechanism: — by reference 


Optional argument. The pl argument is the address of a quadword initialization 
vector used to seed the three modes of the DES algorithm that uses an 
initialization vector. These modes are DESCBC (default), DESCFB, and 
DESMAC; that is, the DES IV initialization vector is a quadword reference 

to an 8-byte value. 


For AES, the optional p1 argument for the AES IV initialization vector is a 
reference to a 16-byte (2 quadword) value. 


If you omit this argument, the initialization vector used is the residue of the 
previous use of the specified context block. ENCRYPT$INIT initializes the 
context block with an initialization vector of zero. 


Description 


ENCRYPT$INIT initializes the context for the encryption operation. 
ENCRYPT$INIT creates preinitialized key tables in the context area to speed 
the encryption or decryption process. Before you can reuse a context with a new 
algorithm, key, or other values specified with ENCRYPTS$INIT, terminate the old 
context with a call to ENCRYPT$FINI. 


Note 


Always initialize the context with ENCRYPT$INIT when you change the 
operation from encryption to decryption or from decryption to encryption. 


ENCRYPTSINIT returns a 32-bit status code indicating the success or failure of 
the routine’s operation. 


Condition Values Returned 


SS$ NORMAL Initialization successfully completed. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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ENCRYPTS$STATISTICS 


Gains access to the statistics maintained by the encryption software. 


Format 

ENCRYPT$STATISTICS context, code, destination, return-length 
Arguments 

context 

type: longword 

access: read only 


mechanism: by reference 


Context area initialized by ENCRYPT$INIT. The context argument is the 
address of a longword initialized by the ENCRYPT$INIT routine. 


code 
type: longword 
access: read only 


mechanism: — by reference 


Code specifying the desired statistic. The code argument is the address of a 
longword containing the code. The only accepted value is 1, which indicates that 
ENCRYPT$STATISTICS is to return all statistics to the destination buffer. 


destination 
type: char_string 
access: write only 


mechanism: — by descriptor 


Buffer into which ENCRYPT$STATISTICS places the statistics. The destination 
argument is the address of a string descriptor describing the buffer. Ensure that 
the destination buffer is at least 20 bytes long and contains: 


e¢ One longword indicating the number of times the primitive has been entered 
referencing this encryption stream 


¢ One quadword indicating the total bytes processed for this stream 


e¢ One quadword indicating the total CPU time, in OpenVMS time format, spent 
on processing requests for this stream 


return-length 

type: longword 
access: write only 
mechanism: by reference 


Number of bytes written to the destination buffer. The return-length argument 
is the address of a word containing the number of bytes. 
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Description 


To track the progress and performance of an encryption operation, the encryption 
software maintains statistics in the context area. You can access these statistics 
with the ENCRYPT$STATISTICS routine. The ENCRYPT$STATISTICS routine 
returns a 32-bit status code indicating the success or failure of the routine’s 
operation. 


Condition Values Returned 


SS$ NORMAL Statistics returned. 

ENCRYPT $xyz An error reported by the Encryption software. 
The xyz portion identifies the message. 

SS$_xyz A return status from a called system service. 


The xyz portion identifies the return status. 
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File Definition Language (FDL) Routines 


This chapter describes the File Definition Language (FDL) routines. These 
routines perform many of the functions of the File Definition Language that 
define file characteristics. Typically, you use FDL to perform the following 
operations: 


e Specify file characteristics otherwise unavailable from your language. 


e Examine or modify the file characteristics of an existing data file to improve 
program or system interaction with that file. 


12.1 Introduction to FDL Routines 


You specify FDL attributes for a data file when you use FDL to create the data 
file, set the desired file characteristics, and close the file. You can then use the 
appropriate language statement to reopen the file. Because the data file is closed 
between the time the FDL attributes are set and the time your program accesses 
the file, you cannot use FDL to specify run-time attributes (attributes that are 
ignored or deleted when the associated data file is closed). 


The FDL$CREATE routine is the one most likely to be called from a high- 

level language. It creates a file from an FDL specification and then closes the 
file. The following HP Fortran program segment creates an empty data file 
named |NCOME93.DAT using the file characteristics specified by the FDL file 
INCOME.FDL. The STATEMENT variable contains the number of the last FDL 
statement processed by FDL$CREATE; this argument is useful for debugging an 
FDL file. 


INTEGER STATEMENT 
INTEGER STATUS, 


2 FDL$CREATE 

STATUS = FDLSCREATE ('INCOME.FDL’, 

2 " INCOME93.DAT’ , 
2 yrage 

2 STATEMENT, 


2 eel 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
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The following three FDL routines provide a way to specify all the options 
OpenVMS RMS allows when it executes create, open, or connect operations. They 
also allow you to specify special processing options required for your applications. 


e The FDL$GENERATE routine produces an FDL specification by interpreting 
a set of RMS control blocks in an existing data file. It then writes the 
FDL specification either to an FDL file or to a character string. If 
your programming language does not provide language statements that 
access RMS control blocks (for example, HP Fortran), you must use 
FDL$GENERATE from within the context of a user-open routine to generate 
an FDL file. 


e The FDL$PARSE routine parses an FDL specification, allocates RMS control 
blocks, and fills in the relevant fields. 


¢ The FDL$RELEASE routine deallocates the virtual memory used by the RMS 
control blocks created by FDL$PARSE. 


These routines cannot be called from asynchronous system trap (AST) level. In 
addition, in order to function properly, these routines require ASTs to remain 
enabled. 


An FDL specification can be in either a file or a character string. When specifying 
an FDL specification in a character string, use semicolons to delimit the 
statements of the FDL specification. 


12.2 Using the FDL Routines: Examples 


This section provides examples that demonstrate the use of the FDL routines in 
various programming scenarios. 


e Example 12-1 shows how to use the FDL$CREATE routine in a Fortran 
program. 

e Example 12-2 shows how to use the FDL$PARSE and FDL$RELEASE 
routines in a C program. 


e Example 12-3 shows a HP Pascal program that uses the FDL$PARSE routine 
to fill in the RMS control blocks in a data file. The program then uses the 
FDL$GENERATE routine to create an FDL file using the information in the 
control blocks. 
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Example 12-1 Using FDL$CREATE in a Fortran Program 


ee ee ee 


eo 


1000 
2000 


This program calls the FDLSCREATE routine. It 
creates an indexed output file named NEW MASTER.DAT 
from the specifications in the FDL file named 
INDEXED.FDL. You can also supply a default filename 
and a result name (that receives the name of the 
created file). The program also returns all the 


statistics. 
IMPLICIT INTEGER* 4 (A - Z) 
EXTERNAL LIBSGET_LUN, FDLSCREATE 
CHARACTER IN_FILE*11 /'INDEXED.FDL'/, 
1 OUT FILE*14 /'NEW_MASTER.DAT’/, 
1 DEF FILE*11 /'DEFAULT. FDL’ /, 
if RES FILE*50 
[INTEGER * 4 FIDBLK (3) /0,0,0/ 
al 
STATUS = FDLSCREATE (IN _FILE,OUT FILE, 

DEF FILE,RES FILE, FIDBLK, , ) 
IF (.NOT. STATUS) CALL LIBSSTOP (%VAL(STATUS) ) 


STATUS=LIBS$GET_ LUN (LOG UNIT) 
OPEN (UNIT=LOG_UNIT,FILE=RES FILE, STATUS=' OLD’ ) 
CLOSE (UNIT=LOG_ UNIT, STATUS=' KEEP’ ) 


WRITE (6,1000) (RES FILE) 
WRITE (6,2000) (FIDBLK (I), I=1,3) 


FORMAT (1X,'The result filename is: ',A50) 
FORMAT (/1X,’FID-NUM: ',15/, 

1 1X,'FID-SEQ: ',15/, 

1 1X,'FID-RVN: ',15) 

END 


Example 12-2 shows how to use the FDL$PARSE and FDL$RELEASE routines in a C 


program. 


Example 12-2 Using FDL$PARSE and FDL$RELEASE in a C Program 


/* 
aK 
aK 
*K 
aK 
aK 
aK 
aK 


*/ 

#inc 
#inc 
#def 


FDLEXAM.C 

This program calls the FDL utility routines FDLS$PARSE and 
FDLSRELEASE. First, FDLS$PARSE parses the FDL specification 
PART.FDL. Then the data file named in PART.FDL is accessed 
using the primary key. Last, the control blocks allocated 
by FDLSPARSE are released by FDLSRELEASE. 

Note; to try this program use the following command on any 
file with textual data: SANALYZE/RMS/FDL/OUT=PART. FDL 


lude <descrip> 
lude <rms> 
ine REC SIZE 80 /* as appropriate for files used */ 


FDLEXAM () 


struct FAB *fab ptr; /* variable to hold pointer to FAB structure */ 
struct RAB *rab ptr; /* variable to hold pointer to RAB structure */ 


SDESCRIPTOR (fdl_ file, "PART.FDL") ; /* free choice of name */ 
char record_buffer [REC SIZE+1] ; /* allow for null terminator */ 
int stat; 


(continued on next page) 
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Example 12-2 (Cont.) Using FDL$PARSE and FDL$RELEASE in a C Program 
/* 


** Read and parse FDL file allocating and initializing RAB and 
** and FAB accordingly, returning pointers to the FAB & RAB. 
*/ 

stat = FDLSPARSE ( &fdl_ file, &fab ptr, &rab ptr ); 

if (! (stat & 1)) LIBSSTOP ( stat ); 


** Try to open file as described by information in the FAB. 

** Signal open errors. Note the usage of STAT, instead of 

** FAB PTR->FABSL STS because just in case the FAB is invalid, 
** the only status returned is STAT. 

k 

/ 

stat = SYSSOPEN ( fab ptr ); 

if (! (stat & 1)) LIBSSTOP ( stat, fab ptr->fab$l1_ stv ); 


stat = SYSSCONNECT ( rab ptr ); 
if (! (stat & 1)) LIBSSTOP ( stat, rab ptr->rab$l_ stv ); 


** Opened the file and connect some internal buffers. 

** Fill in the record output buffer information which is the only 
** missing information in the RAB that was created for us by FDL. 
** Print a header recod and perform the initial S$GET. 

k 
/ 

rab_ptr->rab$w_usz 

rab_ptr->rab$1_ubf 


REC_SIZE; 
record buffer; 


I 


printh: (Wassasssssassasess54 start of records -------------- \n"); 
stat = SYSSGET ( rab ptr ); 
while (stat & 1) /* As long as the $GET is successful */ 
record buffer[rab ptr->rab$w_rsz] = 0; /* Terminate for printf */ 
printf ("%s\n", record_buffer) ; /* Current record */ 
Stat = SYSSGET ( rab ptr ); /* Try to get next one */ 
} 
/* 


** At this point in the execution, the status should be EOF indicating 

** Successfully read the file to end. If not, signal real error. 

wi 

if (stat != RMS$ EOF) LIBSSTOP ( rab ptr->rab$l_ sts, rab ptr->rab$l_ stv ); 


printf ("-------------------- end of records --------------- \n"); 
stat = SYSSCLOSE ( fab ptr ); /* implicit $DISCONNECT */ 

if (!(stat & 1)) LIBSSTOP ( fab ptr->fab$l_ sts, fab ptr->fab$l stv ); 
/* 


** Allow FDL to release the FAB and RAB structures and any other 
** structures (XAB) that it allocated on behalf of the program. 
** Return with its status as final status (success or failure). 
+ 

return FDLSRELEASE ( &fab ptr, &rab ptr ); 
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Example 12-3 shows a HP Pascal program that uses the FDL$PARSE routine to fill in the RMS 
control blocks in a data file, and then uses the FDL$GENERATE routine to create an FDL file. 


Example 12-3 Using FDL$PARSE and FDL$GENERATE in a HP Pascal 


Program 


INHERIT ('SYSSLIBRARY:STARLET’ ) ] 
PROGRAM FDLexample (input, output,order master) ; 


* This program fills in its own FAB, RAB, and * 
* XABs by calling FDLSPARSE and then generates * 
* an FDL specification describing them. * 
* It requires an existing input FDL file * 
* (TESTING.FDL) for FDLSPARSE to parse. * 
TYPE 
Ky * 
* FDL CALL INTERFACE CONTROL FLAGS * 
ke * 
SBIT1 = [BIT(1),UNSAFE] BOOLEAN; 
FDL2STYPE = RECORD CASE INTEGER OF 
1: (FDL$_FDLDEF BITS : [BYTE(1)] RECORD END; 
2: (FDLS$V_SIGNAL : [POS(0)] $BIT1; 
* Signal errors; don’t return * 
FDLS$V_FDL STRING : [POS(1)] $BIT1; 
* Main FDL spec is a char string * 
FDLS$V_DEFAULT STRING : [POS(2)] $BIT1; 
* Default FDL spec is a char string * 
FDL$V_FULL_OUTPUT : [POS(3)] $BIT1; 
* Produce a complete FDL spec * 
FDLS$V_$CALLBACK : [POS(4)] $BIT1; 
* Used by EDIT/FDL on input (DEC only) * 
END; 
mail order = RECORD 
order num : [KEY(0)] INTEGER; 
name : PACKED ARRAY[1..20] OF CHAR; 
address : PACKED ARRAY[1..20] OF CHAR; 
city : PACKED ARRAY[1..19] OF CHAR; 
state : PACKED ARRAY[1..2] OF CHAR; 
zip_code : [KEY(1)] PACKED ARRAY[1..5] 
OF CHAR; 
item num : [KEY(2)] INTEGER; 
shipping : REAL; 
END; 
order file = [UNSAFE] FILE OF mail_order; 
ptr_to FAB = “FABSTYPE; 
ptr to RAB = “RABSTYPE; 
byte = 0..255; 
VAR 
order_ master : order file; 
flags : FDL2STYPE; 
order_rec : mail_order; 
temp _FAB : ptr_to_FAB; 
temp RAB : ptr_to_RAB; 
status : integer; 


(continued on next page) 
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Example 12-3 (Cont.) Using FDL$PARSE and FDL$GENERATE in a HP Pascal 
Program 


FUNCTION FDLSPARSE 
(SSTDESCR FDL FILE : PACKED ARRAY [L..U: INTEGER] 
OF CHAR; 
VAR FAB PTR : PTR_TO FAB; 
VAR RAB PTR : PTR TO RAB) : INTEGER; EXTERN; 


FUNCTION FDLSGENERATE 
(SREF FLAGS : FDL2STYPE; 
FAB PTR : PTR TO FAB; 
RAB PTR : PTR TO RAB; 
SSTDESCR FDL FILE DST : PACKED ARRAY [L..U: INTEGER] 
OF CHAR) : INTEGER; 
EXTERN; 


BEGIN 


status := FDLSPARSE ('TESTING’ , TEMP FAB,TEMP RAB) ; 
flags: :byte := 0; 
status := FDLSGENERATE (flags, 

temp FAB, 

temp RAB, 

"SYSSOUTPUT:') ; 


END. 


12.3 FDL Routines 


This section describes the individual FDL routines. 


Note that the fdl_desc and the default_fdl_desc arguments that are used as 
part of these routine calls are character strings that can be either of the following: 


e A string descriptor pointing to a file that contains a specification 
e A character string that is the actual specification 
For additional details, see the descriptions of the individual routine calls. 
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FDL$CREATE—Create a File from an FDL Specification and Close 


Format 


Returns 


Arguments 


the File 


The FDL$CREATE routine creates a file from an FDL specification and then 
closes the file. 


FDL$CREATE _ fdl_desc [,filename] [,default_name] [,result_name] [,fid_block] [,flags] 
[,stmnt_num] [,retlen] [,sts] [,stv] [,default_fdl_desc] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


fdl_desc 

OpenVMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


The fdl_desc argument is one of the following: 


e A character string descriptor pointing to a file containing the FDL 
specification to be parsed 


e A character string containing the actual FDL specification 


The choice depends on the application making the call. For example, if the 
application wants to create data files that are compatible with a PC application, 
it might create the following FDL file and name it TRANSFER.FDL: 


FILE 

ORGANIZATION sequential 
RECORD 

FORMAT stream lf 


The application could then include the address of the FDL file as the fdl_desc 
argument to the FDL$PARSE call: 


call fdl$parse transfer.fdl ,... 


Optionally, the application might code the FDL specification itself into the call 
using a quoted character string as the fdl_desc argument: 


call fdlSparse "FILE; ORG SEQ; FORMAT STREAM LF;",... 


Note that directly including the FDL specification into the call requires you to do 
the following: 


e Enclose the fdl_dese argument in quotation marks 
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e« Usea semicolon to delimit statements within the fdl_desc argument 
e Assign the symbol FDL$M_FDL_STRING as the flags mask value 


filename 

OpenVMS usage: char_string 

type: character-coded text string 

access: read only 

mechanism: by descriptor—fixed-length string descriptor 


Name of the OpenVMS RMS file to be created using the FDL specification. The 
filename argument is the address of a character string descriptor pointing to the 
RMS file name. This name overrides the default_name parameter given in the 
FDL specification. 


default_name 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


Default name of the file to be created using the FDL specification. The default_ 
name argument is the address of a character string descriptor pointing to the 
default file name. This name overrides any name given in the FDL specification. 


result_name 
OpenVMS usage: char_string 


type: character-coded text string 
access: write only 
mechanism: by descriptor—fixed-length string descriptor 


Resultant name of the file created by FDL$CREATE. The result_name argument 
is the address of a character string descriptor that receives the resultant file 


name. 
fid_block 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


File identification of the RMS file created by FDL$CREATE. The fid_block 
argument is the address of an array of longwords that receives the RMS file 
identification information. The first longword contains the FID_NUM, the second 
contains the FID_SEQ, and the third contains the FID_RVN. They have the 
following definitions: 


FID.NUM The location of the file on the disk. Its value can range from 1 up 
to the number of files the disk can hold. 


FID_SEQ The file sequence number, which is the number of times the file 
number has been used. 

FID_RVN The relative volume number, which is the volume number of the 
volume on which the file is stored. If the file is not stored on a 
volume set, the relative volume number is 0. 
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FDL$CREATE 
flags 
OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or masks) that control how the fdl_desc argument is interpreted and how 
errors are signaled. The flags argument is the address of a longword containing 
the control flags (or a mask). If you omit this argument or specify it as 0, no flags 
are set. The following table shows the flags and their meanings: 


Flag Function 


FDL$V_FDL_STRING Interprets the fdl_desc argument as an FDL 
specification in string form. By default, the fdl_ 
desc argument is interpreted as the file name of an 
FDL file. 

FDL$V_LONG_NAMES ~ Returns the RESULT_NAME using the long result 
name from a long name access block (NAML). By 
default, the RESULT_NAME is returned from the 
short fields of a name access block (NAM) and thus 
may have a generated specification. 

This flag is valid for OpenVMS Alpha only. 

FDL$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


By default, an error status is returned rather than signaled. 


stmnt_num 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


FDL statement number. The stmnt_num argument is the address of a longword 
that receives the FDL statement number. If the routine finishes successfully, 

the stmnt_num argument is the number of statements in the FDL specification. 
If the routine does not finish successfully, the stmnt_num argument receives 
the number of the statement that caused the error. Note that line numbers and 
statement numbers are not the same and that an FDL specification in string form 
has no “lines.” 


retlen 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Number of characters returned in the result_name argument. The retlen 
argument is the address of a longword that receives this number. 


sis 

OpenVMS usage: longword_unsigned 
type: longword_unsigned 
access: write only 
mechanism: by reference 
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RMS status value FAB$L_STS. The sts argument is the address of a longword 
that receives the status value FAB$L_STS from the $CREATE system service. 


stv 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


RMS status value FAB$L_STV. The stv argument is the address of a longword 
that receives the status value FAB$L_STV from the $CREATE system service. 


default_fdl_desc 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


The default_fdl_desc argument is one of the following: 


¢ A character string descriptor pointing to a file containing the default FDL 
specification to be parsed 


e A character string containing the actual default FDL specification 
See the description of the fdl_desc argument for details. 


This argument allows you to specify default FDL attributes. In other words, 
FDL$CREATE processes the attributes specified in this argument unless you 
override them with the attributes you specify in the fdl_desc argument. 


You can code the FDL defaults directly into your program, typically with an FDL 
specification in string form. 
Description 


FDL$CREATE calls the FDL$PARSE routine to parse the FDL specification. The 
FDL specification can be in a file or a character string. 


Source of FDL 


Specification Advantages Disadvantages 
FDL file Variability; for example, if File must be in default directory. 
the specification changes Slower. 


regularly, you can revise 
the file without revising the 
calling program. 


Character You do not have to be Program must be recoded to 
string concerned with locating a change FDL specification. 
file. 


Faster access. 


If the FDL specification is relatively simple and is not going to change, put the 
FDL specification in a character string as the fdl_desc argument to the call. 


FDL$CREATE opens (creates) the specified RMS file and then closes it without 
putting any data in it. 
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FDL$CREATE does not create the output file if an error status is either returned 


or signaled. 


Condition Values Returned 


SS$ NORMAL 
FDL$ ABKW 


FDL$ ABPRIKW 


FDL$ BADLOGIC 
FDL$ CLOSEIN 
FDL$ CLOSEOUT 
FDL$ CREATE 

FDL$ CREATED 
FDL$ CREATED _STM 
FDL$ FDLERROR 
FDL$ ILL_ARG 

FDL$ INSVIREM 
FDL$ INVBLK 


FDL$ MULPRI 
FDL$ OPENFDL 
FDL$ OPENIN 
FDL$ OPENOUT 
FDL$ OUTORDER 


FDL$ READERR 
FDL$ RFLOC 
FDL$ SYNTAX 
FDL$ UNPRIKW 


FDL$ UNQUAKW 
FDL$ UNSECKW 


FDL$ VALERR 
FDL$ VALPRI 
FDL$ WARNING 
FDL$ WRITEERR 
RMS$ ACT 

RMS$ CRE 

RMS$ CREATED 
RMS$ DNF 


Normal successful completion. 


Ambiguous keyword in statement 
number<CRLF >referencetext. 


Ambiguous primary keyword in statement 
number<CRLF >referencetext. 


Internal logic error detected. 

Error closing filename as input. 
Error closing filename as output. 
Error creating filename 

Filename created. 

Filename created in stream format. 
Error parsing FDL file. 

Wrong number of arguments. 
Insufficient virtual memory. 


Invalid RMS control block at virtual address 
‘hex-offset: . 


Multiple primary definition in statement number. 
Error opening filename 

Error opening filename as input. 

Error opening filename as output. 


Key or area primary defined out of order in 
statement number. 


Error reading filename 

Unable to locate related file. 

Syntax error in statement number referencetet. 
Unrecognized primary keyword in statement 


number <CRLF > referencetext. 

Unrecognized qualifier keyword in statement 
number <CRLF > referencetext. 

Unrecognized secondary keyword in statement 
number <CRLF > referencetext. 


Specified value is out of legal range. 

Value required on primary in statement number. 
Parsed with warnings. 

Error writing fileaame 

File activity precludes operation. 

Ancillary control process (ACP) file create failed. 
File was created, not opened. 

Directory not found. 
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FDL$CREATE 


RMS$ DNR 
RMS$ EXP 

RMS$ FEX 

RMS$ FLK 

RMS$ PRV 

RMS$ SUPERSEDE 
RMS$ WLK 
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Device not ready or not mounted. 

File expiration date not yet reached. 

File already exists, not superseded. 

File currently locked by another user. 
Insufficient privilege or file protection violation. 
Created file superseded existing version. 
Device currently write locked. 
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FDL$GENERATE—Generate an FDL Specification 


Format 


Returns 


Arguments 


The FDL$GENERATE routine produces an FDL specification and writes it to 
either an FDL file or a character string. 


FDL$GENERATE flags ,fab_pointer ,rab_pointer [,fdl_file_dst] [,fdl_file_resnam] 
[,fdl_str_dst] [,bad_blk_addr] [,retlen] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or masks) that control how the fdl_str_dst argument is interpreted 

and how errors are signaled. The flags argument is the address of a longword 
containing the control flags (or a mask). If you omit this argument or specify it as 
zero, no flags are set. The flags and their meanings are as follows: 


Flag Function 


FDL$V_FDL_STRING Interprets the fdl_str_dst argument as an FDL 
specification in string form. By default, the fdl_str_ 
dst argument is interpreted as the file name of an 
FDL file. 


FDL$V_FULL_OUTPUT Includes the FDL attributes to describe all the bits 
and fields in the OpenVMS RMS control blocks, 
including run-time options. If this flag is set, every 
field is inspected before being written. By default, 
only the FDL attributes that describe permanent file 
attributes are included (producing a much shorter 
FDL specification). 

FDL$V_LONG_NAMES Returns the FDL_FILE_RESNAME using the long 
result name from a long name access block (NAML). 
By default, the FDL_FILE_RESNAM is returned 
from the short fields of a name access block (NAM) 
and thus may have a generated specification. 

This flag is valid for OpenVMS Alpha only. 
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FDL$GENERATE 
Flag Function 
FDL$V_SIGNAL Signals any error. By default, the status code is 


returned to the calling image. 


By default, an error status is returned rather than signaled. 


fab_pointer 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


RMS file access block (FAB). The fab_pointer argument is the address of a 
longword containing the address of a FAB. 


rab_ pointer 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


RMS record access block (RAB). The rab_pointer argument is the address of a 
longword containing the address of a RAB. 


fdl_file_dst 

OpenVMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


Name of the FDL file to be created. The fdl_file_dst argument is the address of a 
character-string descriptor containing the file name of the FDL file to be created. 
If the FDL$V_FDL_STRING flag is set in the flags argument, this argument 

is ignored; otherwise, it is required. The FDL specification is written to the file 
named in this argument. 


fdl_file_resnam 
OpenVMS usage: char_string 


type: character-coded text string 
access: write only 
mechanism: by descriptor—fixed-length string descriptor 


Resultant name of the FDL file created. The fdl_file_resnam argument is the 
address of a variable character-string descriptor that receives the resultant name 
of the FDL file created (if FDL$GENERATE is directed to create an FDL file). 


fdl_str_dst 

OpenVMS usage: char_string 

type: character-coded text string 

access: write only 

mechanism: by descriptor—fixed-length string descriptor 


FDL specification. The fdl_str_dst argument is the address of a variable 
character string descriptor that receives the FDL specification created. If the 
FDL$V_FDL_STRING bit is set in the flags argument, this argument is required; 
otherwise, it is ignored. 
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FDL$GENERATE 
bad_blk_addr 
OpenVMS usage: address 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an invalid RMS control block. The bad_blk_addr argument is the 
address of a longword that receives the address of an invalid control block (a 

fatal error). If an invalid control block is detected, this argument is returned; 
otherwise, it is ignored. 


retlen 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Number of characters received in either the fdl_file_resnam or the fdl_str_dst 
argument. The retlen argument is the address of a longword that receives this 


number. 


Condition Values Returned 


SS$ NORMAL 
FDL$ INVBLK 
RMS$ ACT 

RMS$ CONTROLC 
RMS$ CONTROLO 
RMS$ CONTROLY 
RMS$ DNR 

RMS$ EXT 

RMS$ OK_ALK 
RMS$ OK_DUP 
RMS$ OK_IDX 
RMS$ PENDING 
RMS$ PRV 

RMS$ REX 

RMS$ RLK 


RMS$ RSA 

RMS$ WLK 

SS$ ACCVIO 
STR$_FATINERR 
STR$_ILLSTRCLA 
STR$_INSVIRMEM 


Normal successful completion. 

Invalid block. 

File activity precludes operation. 

Operation completed under Ctrl/C. 

Output completed under Ctrl/O. 

Operation completed under Ctrl/Y. 

Device not ready or mounted. 

ACP file extend failed. 

Record already locked. 

Record inserted had duplicate key. 

Index update error occurred. 

Asynchronous operation pending completion. 
Insufficient privilege or file protection violation. 
Record already exists. 


Target record currently locked by another 
stream. 


Record stream currently active. 

Device currently write locked. 

Access violation. 

Fatal internal error in run-time library. 
Illegal string class. 

Insufficient virtual memory. 
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FDL$PARSE—Parse an FDL Specification 


The FDL$PARSE routine parses an FDL specification, allocates OpenVMS RMS 
control blocks (FABs, RABs, or XABs), and fills in the relevant fields. 


Format 
FDL$PARSE _ fdl_desc ,fdl_fab_pointer ,fdl_rab_pointer [,flags] [,default_fdl_desc] 
[,stmnt_num] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
fdl_desc 
OpenVMS usage: char_string 
type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


Name of the FDL file or the actual FDL specification to be parsed. See the 
description of the fdl_desc argument for the FDL$CREATE routine for details. 


fdl_fab_pointer 
OpenVMS usage: address 


type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an RMS file access block (FAB). The fdl_fab_pointer argument is the 
address of a longword that receives the address of the FAB. FDL$PARSE both 
allocates the FAB and fills in its relevant fields. 


fdl_rab_pointer 
OpenVMS usage: address 


type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an RMS record access block (for VAX, this is the RAB; for Alpha, it is 
the RAB64). The fdl_rab_pointer argument is the address of a longword that 
receives the address of the RAB or RAB64. FDL$PARSE both allocates the RAB 
or RAB64 and fills in any fields designated in the FDL specification. 


For Alpha, the 64-bit record access block (RAB64) consists of the traditional 
32-bit RAB followed by some 64-bit fields. The RAB64 is automatically allocated 
for Alpha users, who can either use it as a RAB64 or overlay it with the 32-bit 
RAB definition and use it as a traditional 32-bit RAB. 
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FDL$PARSE 
flags 
OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags (or masks) that control how the default_fdl_desc argument is interpreted 
and how errors are signaled. The flags argument is the address of a longword 
containing the control flags. If you omit this argument or specify it as zero, no 
flags are set. The flags and their meanings are as follows: 


Flag Function 


FDL$V_DEFAULT_STRING Interprets the default_fdl_desc argument as 
an FDL specification in string form. By default, 
the default_fdl_desc argument is interpreted 
as the file name of an FDL file. 


FDL$V_FDL_STRING Interprets the fdl_desc argument as an FDL 
specification in string form. By default, the 
fdl_desc argument is interpreted as the file 
name of an FDL file. 


FDL$V_LONG_NAMES Allocates and returns a long name access block 
(NAML) linked to the returned RMS file access 
block (FAB). The appropriate values are set in 
the NAML and FAB blocks so that the long file 
name fields of the NAML block will be used. 

By default, a name block is not allocated and 
the file name fields of FAB are used. 

If the FDL$V_LONG_NAMES flag is set, then 
the FDL$V_LONG_ NAMES bit must also be set 
in the flags argument to the FDL$RELEASE 
routine to ensure that memory allocated for the 
NAML block is deallocated properly. 

This flag is valid for OpenVMS Alpha only. 


FDL$V_SIGNAL Signals any error. By default, the status code is 
returned to the calling image. 


By default, an error status is returned rather than signaled. 


default_fdl_desc 
OpenVMS usage: char_string 


type: character-coded text string 
access: read only 
mechanism: by descriptor—fixed-length string descriptor 


The default_fdl_desc argument is the address of a character-string descriptor 
pointing to either the default FDL file or the default FDL specification. See the 
description of the fdl_desc argument for the FDL$CREATE routine for details. 


This argument allows you to specify default FDL attributes. In other words, 
FDL$PARSE processes the attributes specified in this argument unless you 
override them with the attributes you specify in the fdl_desc argument. 


You can code the FDL defaults directly into your program, typically with an FDL 
specification in string form. 
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FDL$PARSE 
stmnt_num 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


FDL statement number. The stmnt_num argument is the address of a longword 
that receives the FDL statement number. If the routine finishes successfully, 

the stmnt_num argument is the number of statements in the FDL specification. 
If the routine does not finish successfully, the stmnt_num argument receives 
the number of the statement that caused the error. Note that line numbers and 
statement numbers are not the same and that an FDL specification in string form 
has no “lines.” 


By default, an error status is returned rather than signaled. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

LIB$ BADBLOADR Bad block address. 

LIB$ BADBLOSIZ Bad block size. 

LIB$ INSVIRMEM Insufficient virtual memory. 

RMS$ DNF Directory not found. 

RMS$ DNR Device not ready or not mounted. 
RMS$ WCC Invalid wildcard context (WCC) value. 
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FDL$RELEASE—Free Virtual Memory Obtained By FDL$PARSE 


Format 


Returns 


Arguments 


The FDL$RELEASE routine deallocates the virtual memory used by the 
OpenVMS RMS control blocks created by FDL$PARSE. You must use 
FDL$PARSE to populate the control blocks if you plan to deallocate memory 
later with FDL$RELEASE. 


FDL$RELEASE  [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


fab_pointer 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


File access block (FAB) to be deallocated using the LIB$FREE_VM routine. The 
fab_pointer argument is the address of a longword containing the address of the 
FAB. The FAB must be the same one returned by the FDL$PARSE routine. Any 
name blocks (NAMs) and extended attribute blocks (XABs) connected to the FAB 
are also released. 


If you omit this argument or specify it as zero, the FAB (and any associated 
NAMs and XABs) is not released. 


rab_ pointer 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Record access block (RAB) to be deallocated using the LIB$F REE_VM system 
service. The rab_pointer argument is the address of a longword containing the 
address of the RAB. The address of the RAB must be the same one returned by 
the FDL$PARSE routine. Any XABs connected to the RAB are also released. 


If you omit this argument or specify it as zero, the RAB (and any associated 
XABs) is not released. 
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FDL$RELEASE 
flags 
OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flag (or mask) that controls how errors are signaled. The flags argument is the 
address of a longword containing the control flag (or a mask). If you omit this 
argument or specify it as zero, no flag is set. The flag is defined as follows: 


FDL$V_SIGNAL Signals any error. By default, the status code is returned to 
the calling image. 


FDL$V_LONG_ Deallocates any virtual memory used for a long name access 
NAMES block (NAML) created by the FDL$PARSE routine. 
This flag is valid for OpenVMS Alpha only. 
badblk_addr 
OpenVMS usage: address 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Address of an invalid RMS control block. The badblk_addr argument is the 
address of a longword that receives the address of an invalid control block. If 
an invalid control block (a fatal error) is detected, this argument is returned; 
otherwise, it is ignored. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

FDL$ INVBLK Invalid RMS control block at virtual address 
‘hex-offset’ . 

LIB$ BADBLOADR Bad block address. 

RMS$ ACT File activity precludes operation. 

RMS$ RNL Record not locked. 

RMS$ RSA Record stream currently active. 

SS$ ACCVIO Access violation. 
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Librarian (LBR) Routines 


The Librarian (LBR) routines let you create and maintain libraries and their 
modules, and use the data stored in library modules. You can also create and 
maintain libraries at the DCL level by using the DCL command LIBRARY. For 
more information, see the HP OpenVMS DCL Dictionary. 


13.1 Introduction to LBR Routines 


This section briefly describes the types of libraries you can create and maintain 
using LBR routines and how the libraries are structured. This section also lists 
and briefly describes the LBR routines. Section 13.2 provides sample programs 
showing how to use various LBR routines. Section 13.3 is a reference section that 
provides details about each of the LBR routines. 


13.1.1. Types of Libraries 
You can use the LBR routines to maintain the following types of libraries: 


Object libraries, including 164 (ELF) object libraries and Alpha object 
libraries, contain the object modules of frequently called routines. The 
Linker utility searches specified object module libraries when it encounters 

a reference it cannot resolve in one of its input files. For more information 
about how the linker uses libraries, see the description of the Linker utility in 
the HP OpenVMS Linker Utility Manual. 


An object library has a default file type of .OLB and defaults the file type of 
input files to .OBJ . 


Macro libraries contain macro definitions used as input to the assembler. The 
assembler searches specified macro libraries when it encounters a macro that 
is not defined in the input file. For information about defining macros on 
OpenVMS VAX systems, see the VAX MACRO and Instruction Set Reference 
Manual. For information on porting VAX MACRO code to an OpenVMS Alpha 
systems, see the HP OpeVMS MACRO Compiler Porting and User’s Guide 
For information on porting code to 164 systems, see the Porting Applications 
from HP Op~MVMS Alpha to HP Op~mVMS Industry Standard 64 for Integrity 
Servers. 


A macro library has a default file type of .MLB and defaults the file type of 
input files to .MAR. 


Help libraries contain modules of help messages that provide user information 
about a program. You can retrieve help messages at the DCL level by using 
the DCL command HELP, or in your program by calling the appropriate LBR 
routines. For information about creating help modules for insertion into help 
libraries, see the description of the Librarian utility in the HP OpenVMS 
Command Definition, Librarian, and Message Utilities Manual. 


A help library has a default file type of .HLB and defaults the file type of 
input files to .HLP. 


Librarian (LBR) Routines LBR-1 


Librarian (LBR) Routines 
13.1 Introduction to LBR Routines 


¢ Text libraries contain any sequential record files that you want to retrieve as 
data for a program. For example, some compilers can retrieve program source 
code from text libraries. Each text file inserted into the library corresponds 
to one library module. Your programs can retrieve text from text libraries by 
calling the appropriate LBR routines. 


A text library has a default file type of .TLB and defaults the file type of input 
files to .TXT. 


e Shareable image libraries, including 164 (ELF) shareable image libraries and 
Alpha shareable symbol table libraries contain the symbol tables of shareable 
images used as input to the linker. For information about how to create a 
shareable image library, see the descriptions of the Librarian and Linker 
utilities in the HP OpenVMS Command Definition, Librarian, and Message 
Utilities Manual and the HP OpenVMS Linker Utility Manual, respectively. 


A shareable image library has a default type of .OLB and defaults the file 
type of input files to .E XE. 


e National character set (NCS) libraries contain definition modules that define 
collating sequences and conversion functions. NCS libraries have the default 
file type .NLB. For information about how to create an NCS library, see the 
OpemVMS National Character Se Utility Manual. 


e User-developed libraries have characteristics specified when you call the 
LBR$OPEN routine to create a new library. User-developed libraries allow 
you to use the LBR routines to create and maintain libraries that are not 
structured in the form assigned by default to the other library types. Note 
that you cannot use the DCL command LIBRARY to access user-developed 
libraries. 


Table 13-1 shows the libraries that are created by the Librarian utility for each 
OpenVMS platform. 


Table 13-1 Libraries Created by OpenVMS Platforms 


OpenVMS 
OpenVMS VAX OpenVMS Alpha 164 
VAX object Alpha object 164 object 
VAX shareable image Alpha shareable image 164 
shareable 
image 
Alpha object* VAX object? 
Alpha shareable image” VAX shareable image” 
Macro Macro Macro 
Text Text Text 
Help Help Help 


1Use the /ALPHA qualifier to create and manipulate Alpha object and sharable image libraries. 
2Use the /VAX qualifier to create and manipulate VAX object and sharable image libraries. 


1 This manual has been archived but is available on the HP OpMVMS Documentation CD. 
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13.1.2 Structure of Libraries 


You create libraries by executing the DCL command LIBRARY or by calling the 
LBR$OPEN routine. When object, macro, text, help, or shareable image libraries 
are created, the Librarian utility structures them as described in Figure 13-1 and 
Figure 13-2. You can create user-developed libraries only by calling LBR$OPEN; 
they are structured as described in Figure 13-3. 


13.1.2.1_ Library Headers 
Every library contains a library header that describes the contents of the library, 
for example, its type, size, version number, creation date, and number of indexes. 
You can retrieve data from a library's header by calling the LBR$GET HEADER 
routine 


13.1.2.2 Modules 


Each library module consists of a header and data. The data is the information 
you inserted into the library; the header associated with the data is created by 
the LBR routine and provides information about the module, including its type, 
attributes, and date of insertion into the library. You can read and update a 
module’s header by calling the LBR$SET_ MODULE routine. 


13.1.2.3 Indexes and Keys 
Libraries contain one or more indexes, which can be thought of as directories of 
the library’s modules. The entries in each index are keys, and each key consists 
of a key name and a module reference. The module reference is a pointer to the 
module’s header record and is called that record's file address (RFA). Macro, text, 
and help libraries (see Figure 13-1) contain only one index, called the module 
name table. The names of the keys in the index are the names of the modules in 
the library. 


Object and shareable image libraries (see Figure 13-2) contain two indexes: the 
module name table and a global symbol table. The global symbol table consists of 
all the global symbols defined in the modules in the library. Each global symbol 
is a key in the index and points to the module in which it was defined. 


If you need to point to the same module with several keys, you should create 
a user-developed library, which can have up to eight indexes (see Figure 13-3). 
Each index consists of keys that point to the library's modules. 


The LBR routines differentiate library indexes by numbering them, starting with 
1. For all but user-developed libraries, the module name table is index number 
1 and the global symbol table, if present, is index number 2. You number the 
indexes in user-developed libraries. When you access libraries that contain more 
than one index, you may have to call LBR$SET_INDEX to tell the LBR routines 
which index to use. 
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Figure 13-1 Structure of a Macro, Text, or Help Library 


Library Header 


Index (Module Name Table) 


Each key in the index points to a module. 


Modules 


Data Data Data Data 
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Figure 13-2 Structure of an Object or Shareable Image Library 


Library Header 


Index (Module Name Table) 


Each key in the index points to a module. 


Index (Global Symbol Table) 


oa | aa Rel oa 
oa | aa Rel oa 


Each global symbol is a key in the index, and points to the module in 
which it was defined. 


Modules 


Data Data Data Data 
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Figure 13-3 Structure of a User-Developed Library 


Library Header 


Index 


Each key in an index points to one module. More than one key (from 
the same or a different index) may point to the same module. 


Can have up to 
8 indexes. 


Index 


Modules 


Data Data Data Data 
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13.1.3 Summary of LBR Routines 


All the LBR routines begin with the characters LBR$. Your programs can call 
these routines by using the OpenVMS Calling Standard. When you call an LBR 
routine, you must provide all required arguments. Upon completion, the routine 
returns its completion status as a condition value. In addition to the listed 
condition values, some routines may return the success code SS$ NORMAL as 
well as various OpenVMS RMS or system status (SS) error codes. 


When you link programs that contain calls to LBR routines, the linker locates the 
routines during its default search of SYS$SHARE:LBRSHR. Table 13-2 lists the 
routines and summarizes their functions. 


Table 13-2 LBR Routines 


Routine Name Function 
LBR$CLOSE Closes an open library. 
LBR$DELETE_DATA Deletes a specified module's header and data. 


(continued on next page) 
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Table 13-2 (Cont.) LBR Routines 


Routine Name 


Function 


LBR$DELETE_KEY 
LBR$FIND 


LBR$FLUSH 


LBR$GET_HEADER 
LBR$GET_HELP 
LBR$GET_HISTORY 


LBR$GET_INDEX 
LBR$GET_RECORD 
LBR$INI_CONTROL 


LBR$INSERT_KEY 
LBR$LOOKUP_KEY 
LBR$LOOKUP_TY PE 


LBR$MAP_MODULE 
LBR$OPEN 
LBR$OUTPUT_HELP 


LBR$PUT_END 


LBR$PUT_HISTORY 
LBR$PUT_MODULE 


LBR$PUT_RECORD 


LBR$REPLACE_KEY 
LBR$RET_RMSSTV 
LBR$SEARCH 
LBR$SET_INDEX 


LBR$SET_LOCATE 
LBR$SET_ MODULE 


LBR$SET_MOVE 
LBR$UNMAP_MODULE 


Deletes a key from a library index. 


Finds a module by using an address returned by a preceding 
call to LBR$LOOKUP_KEY. 


Writes the contents of modified blocks to the library file and 
returns the virtual memory that contained those blocks. 


Retrieves information from the library header. 
Retrieves help text from a specified library. 


Retrieves library update history records and calls a user- 
supplied routine with each record returned. 


Calls a routine to process modules associated with some or 
all of the keys in an index. 


Reads a data record from the module associated with a 
specified key. 


Initializes a control index that the Librarian uses to identify 
a library. 


Inserts a new key in the current library index. 
Looks up a key in the current index. 


Searches the index for the key from a particular module 
(RFA) and returns the key’s type for that module 


164 only. Maps a module in P2 space. 
Opens an existing library or creates a new one. 


Retrieves help text from an explicitly named library or from 
user-supplied default libraries, and optionally prompts you 
for additional help queries. 


Terminates the writing of a sequence of records to a module 
using the LBR$PUT_RECORD routine. 


Inserts a library update history record. 


(164 only.) Puts an entire module, with the module's file 
address (RFA), from memory space into the current library. 


Writes a data record to the module associated with the 
specified key. 


Replaces an existing key in the current library index. 
Returns the last RMS status value. 
Finds index keys that point to specified data. 


Sets the index number to be used during processing of the 
library. 


Sets Librarian subroutine record access to locate mode. 


Reads and optionally updates a module header associated 
with a given record's file address (RFA). 


Sets Librarian subroutine record access to move mode. 
(164 only.) Unmaps a module from process P2 space. 
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13.2 Using the LBR Routines: Examples 


This section provides programming examples that call LBR routines. Although 
the examples do not illustrate all the LBR routines, they do provide an 
introduction to the various data structures and the calling syntax. 


The program examples are written in HP Pascal and the subroutine examples are 
written in HP Fortran. The listing of each program example contains comments 
and is followed by notes about the program. The highlighted numbers in the 
notes are keyed to the highlighted numbers in the examples. 


Each sample program calls the LBR$INI_ CONTROL routine and the LBR$OPEN 
routine before calling any other routine. 
Note 


The one exception is that when you call the LBRS0UTPUT_HELP 
routine, you need not call the LBR$INI_CONTROL routine and the 
LBR$OPEN routine 


The sample programs require access to various symbols derived from definition 
macros. Use the INHERIT attribute to access these symbols from definition 
macros in SYS$LIBRARY:STARLET.PEN. 


The LBR$INI_CONTROL routine sets up a control index; do not confuse this 
with a library index. The control index is used in subsequent LBR routine calls 
to identify the applicable library (because you may want your program to work 
with more than one library at a time). 


Note 


Do not alter the control index value. 


LBR$INI_CONTROL specifies the library function, which can be to either create 
and update a new library (LIB$C_CREATE), modify an existing library (LIB$C_ 
UPDATE), or read an existing library without updating it (LIB$C_ READ). 


Upon completion of the LBR$INI_CONTROL routine, call the LBR$OPEN 
routine to open the library. Open an existing library, or create and open a new 
library, in either the UPDATE or READ mode, checking for an error status value 
of RMS$ FNF. If this error occurs, open the library in CREATE mode. 


When you open the library, specify the library type and pass the file specification 
or partial file specification of the library file. 


If you are creating a new library, pass the create options array. The CRE symbols 
identify the significant longwords of the array by their byte offsets into the array. 
Convert these values to subscripts for an array of integers (longwords) by dividing 
by 4 and adding 1. If you do not load the significant longwords before calling 
LBR$INI_CONTROL, the library may be corrupted upon creation. 


Finally, pass any defaults for the file specification. If you omit the device and 
directory parts of the file specification, the current default device and directory 
are used. 


Librarian (LBR) Routines LBR-7 


Librarian (LBR) Routines 
13.2 Using the LBR Routines: Examples 


When you finish working with a library, call LBR$CLOSE to close the library 
by providing the control index value. You must close a library explicitly before 
updates can be posted. Remember to call LBR$INI_ CONTROL again if you want 
to reopen the library. LBR$CLOSE deallocates all the memory associated with 
the library, including the control index. 


The order in which you call the routines between LBR$OPEN and LBR$CLOSE 
depends upon the library operations you need to perform. You may want to call 
LBR$LOOKUP_KEY or LBR$GET_INDEX to find a key, then perform some 
operation on the module associated with the key. You can think of a module as 
being both the module itself and its associated keys. To access a module, you first 
need to access a key that points to it; to delete a module, you first need to delete 
any keys that point to it. 


Note 


Do not use LBR$INI_CONTROL, LBR$OPEN, and LBR$CLOSE 
for writing help text with LBR$OUTPUT_ HELP. Simply invoke 
LBR$OUTPUT_HELP. 


13.2.1 Creating, Opening, and Closing a Text Library 


Example 13-1 is a sample HP Pascal program that creates, opens, and then 
closes a text library. The program is summarized in the following steps: 


1. Initialize the library—Call LBR$INI_CONTROL to initialize the library. 
2. Open the library—Call LBR$OPEN to open the library. 
3. Close the library—Call LBR$CLOSE to close the library. 
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Example 13-1 Creating a New Library Using HP Pascal 


PROGRAM createlib (INPUT, OUTPUT) ; 
(*This program creates a text library*) 


TYPE (*Data type of*) 
Create Array = ARRAY [1..20] OF INTEGER; (*create options array*) 
VAR (*Constants and return status error 


codes for LBR$ OPEN & LBRSINI_ CONTROL. 

These are defined in $LBRDEF macro*) 
LBRSC_CREATE, LBR$C_TYP_TXT,LBRS$ ILLCREOPT,LBRS$ ILLCTL, 
LBR$_ILLFMT,LBRS$ NOFILNAM,LBRS OLDMISMCH,LBRS$ TYPMISMCH : 

[EXTERNAL] INTEGER; 

(*Create options array codes. These 
are defined in $CREDEF macro*) 
CRE$L_TYPE,CRE$L_KEYLEN, CRE$L ALLOC, CRESL_IDXMAX, CRESL_ENTALL, 
CRESL LUHMAX, CRESL VERTYP,CRESL IDXOPT,CRESC_MACTXTCAS, 


CRESC_VMSV3 : [EXTERNAL] INTEGER; 

Lib Name : VARYING [128] OF CHAR; (*Name of library to create*) 

Options : Create Array; (*Create options array*) 

File Type : PACKED ARRAY [1..4] (*Character string that is default*) 
OF CHAR := ’.TLB’; (*file type of created lib file*) 

lib index ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return Status for function calls*) 


(*-*-*-*-Function and Procedure Definitions-*-*-*-*) 
(*Function that returns library 
control index used by Librarian*) 
FUNCTION LBRSINI_CONTROL (VAR library _index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 
INTEGER; EXTERN; 


(*Function that creates/opens library*) 


FUNCTION LBRSOPEN (library index: UNSIGNED; 
fns: [class_s] PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create options: Create Array; 
dns: [CLASS S] PACKED ARRAY [13..u3: INTEGER] OF CHAR; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := SIMMED 0; 
rns: [CLASS S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 

%IMMED 0; 
VAR rnslen: INTEGER := SIMMED 0): 
INTEGER; EXTERN; 


(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 
INTEGER; EXTERN; 
(*Error handler to check error codes 
if open/create not successful*) 


(continued on next page) 
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Example 13-1 (Cont.) Creating a New Library Using HP Pascal 


PROCEDURE Open Error; C3) 
BEGIN 
WRITELN(’Open Not Successful’); (*Now check specific error codes*) 
IF status IADDRESS (LBR$ ILLCREOPT) THEN 
WRITEL Create Options Not Valid Or Not Supplied’) ; 
IF stat IADDRESS (LBR$ ILLCTL) THEN 
WRITEL Invalid Library Index’) ; 
IF stat IADDRESS (LBR$ ILLFMT) THEN 
Library Not In Correct Format’) ; 
IADDRESS (LBR$ NOFILNAM) THEN 
WRITEL Library Name Not Supplied’) ; 
IF status IADDRESS (LBR$ OLDMISMCH) THEN 
WRITELN (' Old Library Conflict’); 
IF status = IADDRESS(LBR$ TYPMISMCH) THEN 
WRITELN (' Library Type Mismatch’ ) 
END; (*of procedure Open Error*) 
BEGIN (* RKKKKKKKEKKKKKEKE DECLARATIONS COMPLETE KREEKKKKEKRKKEKEKKRKEKR KEKE KEKEKEE 
KKKKKKKKKKKKEKK MATN PROGRAM BEGINS HERE FRR KKK KKK KKK KKKKKEKKKK *) 
(*Prompt for Library Name*) 
WRITE ('Library Name: '); READLN(Lib Name) ; 
(*Fill Create Options Array. Divide 
by 4 and add 1 to get proper subscript*) 
L_ TYPE) DIV 4 + 1] := IADDRESS (LBR$C_TYP_ TXT) ; 
| KEYLEN) DIV 4 + 1] := 31; 14) 
, ALLOC) DIV 4 +1] := 8; 
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Options [IADDRESS 
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Options [IADDRESS 


3] 


4 +4 1) ly 
L 44+ 1] := 96; 
L LUHMAX) DIV 4 + 1] := 20; 
Ls 4 

4 


L VERTYP) DIV + 1] := IADDRESS (CRESC_| VMSV3) ; 
L_IDXOPT) DIV + 1] := IADDRESS ( (CRESC_|  MACTXTCAS) ; 
(*Initialize library control index*) 
status := LBRSINI CONTROL (lib index ptr, 
IADDRESS (LBRSC_CREATE) , (*Create access*) 
IADDRESS (LBRSC_' TYP TXT) ) ; (*Text library*) 
IF NOT ODD(status) THEN (*Check return status*) 
WRITELN (‘Initialization Failed’) 
ELSE (*Initialization was successful*) 
BEGIN (*Create and open the library*) 
status := LBRSOPEN (lib index ptr, 
Lib Name, 
Options, 16) 
File Type) ; 
IF NOT ODD(status) THEN (*Check return status*) 
Open Error (*Call error handler*) 7) 
ELSE (*Open/create was successful*) 
BEGIN (*Close the library*) 
status := LBRSCLOSE(lib index ptr) ; 
IF NOT ODD(status) THEN (*Check return status*) 
WRITELN('Close Not Successful’ ) 


Se Ee ee UW 
Gi wW 
ka 
o 
ES 
Es 
l=] 
HA 
<j 


Aww aee 


CO OAH Qa2 OQ 
AAAAAA A 


END 
END 
END. (*of program creatlib*) 


Each item in the following list corresponds to a number highlighted in 
Example 13-1: 


@ Usethe INHERIT attribute to access the LBR and CRE symbols from 
SYS$LIBRARY:STARLET.PEN. 
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@ Start the declarations of the LBR routines that are used by the program. 
Each argument to be passed to the Librarian is specified on a separate line 
and includes the name (which just acts as a placeholder) and data type (for 
example: UNSIGNED, which means an unsigned integer value, and PACKED 
ARRAY OF CHAR, which means a character string). If the argument is 
preceded by VAR, then a value for that argument is returned by the LBR to 
the program. 


© Declare the procedure Open Error, which is called in the executable section 
if the Librarian returns an error when LBR$OPEN is called. Open_Error 
checks the Librarian’s return status value to determine the specific cause 
of the error. The return status values for each routine are listed in the 
descriptions of the routines. 


Initialize the array called Options with the values the Librarian needs to 
create the library. 


Call LBR$INI_CONTROL, specifying that the function to be performed is 
create and that the library type is text. 


Call LBR$OPEN to create and open the library; pass the Options array 
initialized in item 5 to the Librarian. 


eo © Oo 8 


If the call to LBR$OPEN was unsuccessful, call the procedure Open_Error 
(see item 4) to determine the cause of the error. 


13.2.2 Inserting a Module 


Example 13-2 illustrates the insertion of a module into a library from a HP 
Pascal program. The program is summarized in the following steps: 


1. Ensure that the module does not already exist by calling LBR$LOOKUP_ 
KEY. The return status should be LBR$ KEYNOTFND. This step is optional. 


2. Construct the module by calling LBR$PUT RECORD once for each record 
going into the module. Pass the contents of the record as the second 
argument. LBR$PUT_RECORD returns the record file address (RFA) in 
the library file as the third argument on the first call. On subsequent calls, 
you pass the RFA as the third argument, so do not alter its value between 
calls. 


Call LBR$PUT_END after the last call to LBR$PUT_ RECORD. 


4. Call LBR$INSERT_KEY to catalog the records you have just put in the 
library. The second argument is the name of the module. 


To replace an existing module, save the RFA of the module header returned by 
LBR$LOOKUP_KEY in Step 1 in one variable and the new RFA returned by the 
first call to LBR$PUT_RECORD (Step 2) in another variable. In Step 4, invoke 
LBR$REPLACE_KEY instead of LBR$INSERT_KEY, pass the old RFA as the 
third argument, and the new RFA as the fourth argument. 
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Example 13-2 Inserting a Module into a Library Using HP Pascal 


PROGRAM insertmod (INPUT, OUTPUT) ; 

(*This program inserts a module into a library*) 
TYPE 
Rfa_Ptr = ARRAY [0. 


.1] OF INTEGER; (*Data type of RFA of module*) 


VAR 


LBRSC_UPDATE, 
LBRSC_TYP TXT, 


(*Constants for LBRSINI_CONTROL* ) 
(*Defined in SLBRDEF macro*) 


LBRS$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBRSLOOKUP_KEY*) 
Lib Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module Name : VARYING [31] OF CHAR; (*Name of module to insert*) 


Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 


Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 

lib index ptr : UNSIGNED; (*Value returned in library init*) 
status : UNSIGNED; (*Return status for function calls*) 
txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 

Key Not_Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 


(*-*-*-*-Function Definitions-*-*-*-*) 
(*Function that returns library 
control index used by Librarian*) 
FUNCTION LBRSINI_CONTROL (VAR library index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER SIMMED 0): 


INTEGER; EXTERN; 
(*Function that creates/opens library*) 


FUNCTION LBRSOPEN (library index: UNSIGNED; 


fns: [class_s] PACKED ARRAY[1..u: INTEGER] OF CHAR; 

create options: ARRAY [12..u2:INTEGER] OF INTEGER := 
SIMMED 0; 

dns: [CLASS S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= SIMMED 0; 


rlfna: ARRAY [14..u4:INTEGER] OF INTEGER SIMMED 0; 
rns: [CLASS S] PACKED ARRAY [15..u5:INTEGER] OF CHAR : 
SIMMED 0; 
VAR rnslen: INTEGER 
INTEGER; EXTERN; 


:= SIMMED 0): 


(*Function that finds a key in index*) 
FUNCTION LBRSLOOKUP_KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [1l..u: INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_ Ptr): 


INTEGER; EXTERN; 
(*Function that inserts key in index*) 
FUNCTION LBRSINSERT KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR ; 
txtrfa: Rfa_ Ptr): 
INTEGER; EXTERN; 
(*Function that writes data records*) 


(continued on next page) 
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Example 13-2 (Cont.) Inserting a Module into a Library Using HP Pascal 


FUNCTION LBRSPUT_ RECORD (library index: UNSIGNED; (*to modules*) 
textline: [CLASS S] PACKED ARRAY [1l..u:INTEGER] OF 
CHAR; 


txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 
(*Function that marks end of a module*) 
FUNCTION LBRSPUT_END (library index: UNSIGNED) : 
INTEGER; EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 
INTEGER; EXTERN; 
BEGIN (* RKKEKKEKKEKEKKEKKKKE DECLARATIONS COMPLETE KKK KKKKKEKRKEKEKKEKREKRKKEKKEKEKEEE 


KkEKKEKKKKEKEKE MATN PROGRAM BEGINS HERE #44 kKKKKKKKKEEKKKKKK &) 
*Prompt for library name and 
module to insert*) 
WRITE('Library Name: '); READLN(Lib Name) ; 
WRITE(‘’Module Name: '); READLN (Module Name) ; 
*Initialize lib for update access*) 
status := LBRSINI_ CONTROL (lib index ptr, 
IADDRESS (LBRS$C_UPDATE) , (*Update access*) 
IADDRESS (LBRSC_TYP TXT)); (*Text library*) 
IF NOT ODD(status) THEN *Check error status*) 
WRITELN (‘Initialization Failed’ ) 
ELSE *Initialization was successful*) 
BEGIN 
status := LBRSOPEN (lib index ptr, (*Open the library*) 
Lib Name) ; 
IF NOT ODD(status) THEN *Check error status*) 
WRITELN (‘Open Not Successful’ ) 
ELSE *Open was successful*) 
BEGIN *Is module already in the library?*) 
status := LBRSLOOKUP_KEY (lib _index ptr, 
Module Name, 
txtrfa_ptr) ; 
IF ODD(status) THEN (*Check status. Should not be odd*) 
WRITELN('Lookup key was successful.’, 
‘The module is already in the library.’) 
ELSE (*Did lookup key fail because key not found?*) 
IF status = IADDRESS(LBR$ KEYNOTFND) THEN 3] 
Key Not_Found := TRUE 
END 
END; 


(continued on next page) 
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Example 13-2 (Cont.) Inserting a Module into a Library Using HP Pascal 


(******T£ LBRSLOOKUP KEY failed because the key was not found 
(as expected), we can open the file containing the new module, 
and write the module’s records to the library file*******) 
IF Key Not_Found THEN 
BEGIN 
OPEN (Textin, Module Name, old) ; 
RESET (Textin) ; 


WHILE NOT EOF(Textin) DO (*Repeat until end of file*) 
BEGIN 
READ (Textin, Text_Data_Record) ; (*Read record from 
external file*) 
status := LBRSPUT_RECORD (lib index ptr, (*Write*) 
Text_Data_Record, (*record to*) 
txtrfa_ptr) ; (*library*) 


IF NOT ODD(status) THEN 
WRITELN(’Put Record Routine Not Successful’) 
END; (*of WHILE statement*) 
IF ODD(status) THEN (*True if all the records have been 
successfully written into the library*) 
BEGIN 
status := LBRSPUT_END (lib index ptr); (*Write end of 
module record*) 
IF NOT ODD(status) THEN 
WRITELN(’Put End Routine Not Successful’ ) 
ELSE (*Insert key for new module*) 
BEGIN 
status := LBRSINSERT KEY (lib index ptr, 
Module Name, 
txtrfa_ptr) ; 


eS 


F NOT ODD(status) THEN 
WRITELN('Insert Key Not Successful’ ) 
END 
END 
END; 
status := LBRSCLOSE(lib index ptr) ; 
IF NOT ODD(status) THEN 
WRITELN('Close Not Successful’ ) 
END. (*of program insertmod*) 


Each item in the following list corresponds to a number highlighted in 
Example 13-2: 


@ Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and that the library type is text. 


Call LBR$LOOKUP_KEY to see whether the module to be inserted is already 
in the library. 


2) 

© Call LBR$LOOKUP_KEY to see whether the lookup key failed because the 
key was not found. (In this case, the status value is LBR$ KEYNOTFND.) 

4) 


Read a record from the input file, then use LBR$PUT_RECORD to write the 
record to the library. When all the records have been written to the library, 
use LBR$PUT_END to write an end-of-module record. 


@ UseLBR$INSERT_KEY toinsert a key for the module into the current index. 
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Example 13-3 illustrates the extraction of a library module from a HP Pascal 
program. The program is summarized in the following steps: 


1. Call LBR$LOOKUP_KEY to locate the module. Specify the name of the 
module as the second argument. LBR$LOOKUP_KEY returns the RFA of the 
module as the third argument; do not alter this value. 


2. Call LBR$GET_ RECORD once for each record in the module. Specify a 
character string to receive the extracted record as the second argument. 
LBR$GET_RECORD returns a status value of RMS$ EOF after the last 
record in the module is extracted. 


Example 13-3 Extracting a Module from a Library Using HP Pascal 


PROGRAM extractmod (INPUT, OUTPUT, Textout) ; 
(*This program extracts a module from a library*) 


TYPE 


Rfa_Ptr = ARRAY [0..1] 


VAR 
LBRSC_UPDATE, 


LBRS$C_TYP TXT, 
RMS$ EOF : [EXTERNAL] INTEGER; 


Lib Name : 
Module Name : 


Extracted File : 


VARYING [128] 
VARYING [31] 


OF INTEGER; *Data type of RFA of module*) 

*Constants for LBRSINI_CONTROL*) 
(*Defined in $LBRDEF macro*) 

*RMS return status; defined in 

SRMSDEF macro*) 

(*Name of library receiving module*) 

*Name of module to insert*) 

(*Name of file to hold 

extracted module*) 


OF CHAR; 
OF CHAR; 
VARYING [31] OF CHAR; 


Outtext : PACKED ARRAY [1..255] OF CHAR; *Extracted mod put here, *) 

Outtext2 : VARYING [255] OF CHAR; * then moved to here*) 

i: INTEGER; *For loop control*) 

Textout : FILE OF VARYING [255] OF CHAR; *File containing extracted 
module* ) 

nullstring : CHAR; *nullstring, pos, and len used to*) 

pos, len : INTEGER; *find string in extracted file recd*) 

lib index ptr : UNSIGNED; *Value returned in library init*) 

status : UNSIGNED; *Return status for function calls*) 

txtrfa_ptr : Rfa_Ptr; *For key lookup and insertion*) 


(*-*-*-*-Function Definitions-*-*-*-*) 


(*Function that returns library 
control index used by Librarian*) 


FUNCTION LBRSINI_CONTROL (VAR library _index: UNSIGNED; 


INTEGER; EXTERN; 


FUNCTION LBRSOPEN 


func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u:INTEGER] 
OF INTEGER := $IMMED 0): 


(*Function that creates/opens library*) 
(library index: UNSIGNED; 
fns: [class_s] PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create options: ARRAY [12..u2:INTEGER] OF INTEGER := 
SIMMED 0; 


dns: [CLASS $] PACKED ARRAY [13..u3: INTEGER] OF CHAR 

:= %IMMED 0; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS $] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 


%IMMED 0; 


VAR rnslen: INTEGER := %IMMED 0): 


INTEGER; EXTERN; 


(continued on next page) 
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Example 13-3 (Cont.) Extracting a Module from a Library Using HP Pascal 


(*Function that finds a key in an index*) 
FUNCTION LBRSLOOKUP_KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_Ptr): 
INTEGER; EXTERN; 


(*Function that retrieves records from modules*) 
FUNCTION LBRSGET_ RECORD (library index: UNSIGNED ; 
var textline: [CLASS S] PACKED ARRAY [l..u:INTEGER] OF 
CHAR) : 
INTEGER; 


EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 


INTEGER; EXTERN; 
BEGIN (* doROR ee DECLARATIONS COMPLETE (00 G GOOG I IC ie 


kkEKKKKKKKKKKEK MATN PROGRAM BEGINS HERE #44 ke KKKKKKKKERKKKEKK ) 
(* Get Library Name, Module To Extract, And File To Hold Extracted Module *) 


WRITE(‘’Library Name: '); READLN(Lib Name) ; 

WRITE (’Module Name: '); READLN(Module Name) ; 
WRITE('Extract Into File: '); READLN (Extracted_File) ; 
status := LBRSINI_CONTROL (lib index ptr, 1) 


IADDRESS (LBR$C_UPDATE) , 
IADDRESS (LBRSC_TYP_TXT)) ; 


IF NOT ODD(status) THEN 
WRITELN (‘Initialization Failed’) 


ELSE 
BEGIN 
status := LBRSOPEN (lib index ptr, 
Lib Name) ; 
IF NOT ODD(status) THEN 
WRITELN('Open Not Successful’) 
ELSE 
BEGIN 12) 
status := LBRSLOOKUP_KEY (lib index ptr, 
Module Name, 
txtrfa_ptr) ; 
IF NOT ODD(status) THEN 
WRITELN (‘Lookup Key Not Successful’ ) 
ELSE 
BEGIN 13) 
OPEN (Textout, Extracted File,new) ; 
REWRITE (Textout) 
END 
END 
END; 
WHILE ODD(status) DO 
BEGIN 
nullstring := '' (0); 
FOR i := 1 TO 255 DO 4) 
Outtext [i] := nullstring; 
status := LBRSCET RECORD (lib index ptr, 


Outtext) ; 
IF NOT ODD(status) THEN 
BEGIN 5] 
IF status = IADDRESS(RMS$ EOF) THEN 
WRITELN(’ RMS end of file’) 
END 


(continued on next page) 
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Example 13-3 (Cont.) Extracting a Module from a Library Using HP Pascal 


END. 


ELSE 
BEGIN 6) 
pos := INDEX(Outtext, nullstring); (*find first null 
in Outtext*) 
len := pos - 1; (*length of Outtext to first null*) 
IF len >= 1 THEN 
BEGIN 
Outtext2 := SUBSTR(Outtext,1, LEN) ; 
WRITE (Textout , Outtext2) 
END 
END 
END; (*of WHILE*) 
status := LBRSCLOSE(lib index ptr) ; 
IF NOT ODD(status) THEN 
WRITELN(’Close Not Successful’ ) 
(*of program extractmod*) 


Each item in the following list corresponds to a number highlighted in 
Example 13-3: 


1] 
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Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and that the library type is text. 


Call LBR$LOOKUP_KEY to find the key that points to the module you want 
to extract. 


Open an output file to receive the extracted module. 


Initialize the variable that is to receive the extracted records to null 
characters. 


Call LBR$GET_RECORD to see if there are more records in the file (module). 
A failure indicates that the end of the file has been reached. 


Write the extracted record data to the output file. This record should consist 
only of the data up to the first null character. 


13.2.4 Deleting a Module 


Example 13-4 illustrates the deletion of library module from a HP Pascal 
program. The program is summarized in the following steps: 


.e 


Call LBR$LOOKUP_KEY, and specify the name of the module as the second 
argument. LBR$LOOKUP_KEY returns the RFA of the module as the third 
argument; do not alter this value. 


Call LBR$DELETE KEY to delete the module key. Specify the name of the 
module as the second argument. 


Call LBR$DELETE_DATA to delete the module itself. Specify the RFA of the 
module obtained in Step 1 as the second argument. 
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Example 13-4 Deleting a Module from a Library Using HP Pascal 


PROGRAM deletemod (INPUT, OUTPUT) ; 
(*This program deletes a module from a library*) 


TYPE 
Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 

VAR 
LBRSC_UPDATE, (*Constants for LBRSINI_CONTROL*) 
LBRSC_TYP TXT, (*Defined in SLBRDEF macro*) 
LBR$ _KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBRSLOOKUP_KEY*) 
Lib Name : VARYING [128] OF CHAR; *Name of library receiving module*) 


Module Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 


lib index ptr : UNSIGNED; *Value returned in library init*) 
status : UNSIGNED; (*Return status for function calls*) 
txtrfa_ptr : Rfa Ptr; *For key lookup and insertion*) 

Key Not_Found : BOOLEAN := FALSE; *True if new mod not already in lib*) 


(*-*-*-*-Function Definitions-*-*-*-*) 
(*Function that returns library 
control index used by Librarian*) 
FUNCTION LBRSINI_ CONTROL (VAR library index: UNSIGNED; 
func: UNSIGNED; 
typ: UNSIGNED; 
VAR namblk: ARRAY[1..u: INTEGER] 
OF INTEGER := %IMMED 0): 


INTEGER; EXTERN; 
*Function that creates/opens library*) 
FUNCTION LBRSOPEN (library index: UNSIGNED; 
fns: [class_s] PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create options: ARRAY [12..u2:INTEGER] OF INTEGER := 
SIMMED 0; 
dns: [CLASS S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= SIMMED 0; 
vlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
SIMMED 0; 
VAR rnslen: INTEGER := SIMMED 0): 
INTEGER; EXTERN; 


(*Function that finds a key in index*) 
FUNCTION LBRSLOOKUP_KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [1l..u:INTEGER] OF 
CHAR; 
VAR txtrfa: Rfa_ Ptr): 
INTEGER; EXTERN; 
(*Function that removes a key from an index*) 
FUNCTION LBRSDELETE KEY (library index: UNSIGNED; 
key name: [CLASS S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR) : 
INTEGER ; 


EXTERN; 


(*Function that deletes all the records 
associated with a module*) 
FUNCTION LBRSDELETE DATA (library index: UNSIGNED ; 
txtrfa: Rfa_ Ptr): 
INTEGER; 
EXTERN; 
(*Function that closes library*) 
FUNCTION LBRSCLOSE (library index: UNSIGNED) : 
INTEGER; EXTERN; 


(continued on next page) 
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Example 13-4 (Cont.) Deleting a Module from a Library Using HP Pascal 


BEGIN (* **k*kekee RHE DECLARATIONS COMPLETE (00 OR ICI Ie 


KKKKKKKKKKKKKEK MATN PROGRAM BEGINS HERE FREER ERK REE EKER KEKERK *) 
(* Get Library Name and Module to Delete *) 
WRITE(’Library Name: '); READLN(Lib Name) ; 
WRITE(’Module Name: '); READLN (Module Name) ; 
*Initialize lib for update access*) 
status := LBRSINI CONTROL (lib index ptr, 
IADDRESS (LBRS$C_UPDATE) , (*Update access*) 
IADDRESS (LBRSC_TYP_TXT)); (*Text library*) 
IF NOT ODD(status) THEN *Check error status*) 
WRITELN(’Initialization Failed’) 
ELSE *Initialization was successful*) 
BEGIN 
status := LBRSOPEN (lib index ptr, (*Open the library*) 
Lib Name) ; 
IF NOT ODD(status) THEN *Check error status*) 
WRITELN(’Open Not Successful’ ) 
ELSE *Open was successful*) 
BEGIN @® (*Is module in the library?*) 
status := LBRSLOOKUP_KEY (lib index ptr, 
Module Name, 
txtrfa_ptr) ; 
IF NOT ODD(status) THEN (*Check status*) 
WRITELN('Lookup Key Not Successful’) 
END 
END; 
IF ODD(status) THEN (*Key was found; delete it*) 
BEGIN 
status := LBRSDELETE KEY (lib index ptr, 3] 


Module Name) ; 
IF NOT ODD(status) THEN 
WRITELN('Delete Key Routine Not Successful’) 


ELSE (*Delete key was successful*) 
BEGIN (*Now delete module's data records*) 
status := LBRSDELETE DATA (lib index ptr, 
txtrfa_ptr) ; 


IF NOT ODD(status) THEN 
WRITELN('Delete Data Routine Not Successful’ ) 
END 

END; 
status := LBRSCLOSE(lib index ptr); (*Close the library*) 
IF NOT ODD(status) THEN 

WRITELN('Close Not Successful’); 

END. (*of program deletemod*) 


Each item in the following list corresponds to a number highlighted in 
Example 13-4: 


@ Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and the library type is text. 


® Call LBR$LOOKUP_KEY to find the key associated with the module you 
want to delete. 


© Call LBR$DELETE_KEY to delete the key associated with the module you 
want to delete. If more than one key points to the module, you need to call 
LBR$LOOKUP_KEY and LBR$DELETE_KEY for each key. 


@ Call LBR$DELETE_DATA to delete the module (the module header and data) 
from the library. 
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13.2.5 Using Multiple Keys and Multiple Indexes 


You can point to the same module with more than one key. The keys can be in 
the primary index (index 1) or alternate indexes (indexes 2 through 10). The 
best method is to reserve the primary index for module names. In system-defined 
object libraries, index 2 contains the global symbols defined by the various 
modules. 


Example 13-5 illustrates the way that keys can be associated with modules. 


Example 13-5 Associating Keys with Modules 


SUBROUTINE ALIAS (INDEX) 
! Catalogs modules by alias 


INTEGER STATUS, ! Return status 
INDEX, ! Library index 
TXTRFA (2) ! RFA of module 
CHARACTER*31 MODNAME, ! Name of module 
ALIASNAME ! Name of alias 
INTEGER MODNAME_ LEN ! Length of module name 
INTEGER ALIASNAME LEN ! Length of alias name 
! VMS library procedures 
INTEGER LBRSLOOKUP_KEY, 
LBRSSET_INDEX, 
LBRSINSERT_KEY, 
LIBSGET_INPUT, 
LIBSGET_ VALUE 
LIBSLOCC 
! Return codes 
EXTERNAL LBRS$ KEYNOTFND, ! Key not found 


LBR$ DUPKEY, ! Duplicate key 
RMSS$_EOF, ! End of text in module 
DOLIB NOMOD ! No such module 


! Get module name from /ALIAS on command line 

CALL CLISGET VALUE (‘’ALIAS’, MODNAME) 

! Calculate length of module name 

MODNAME LEN = LIBSLOCC (’ ‘, MODNAME) - 1 

! Look up module name in library index 

STATUS = LBRSLOOKUP_KEY (INDEX, 
MODNAME (1:MODNAME LEN), 
TXTRFA) 


END IF 


(continued on next page) 
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Example 13-5 (Cont.) Associating Keys with Modules 


! Insert aliases if module exists 
IF (STATUS) THEN 
! Set to index 2 
STATUS = LBRSSET_INDEX (INDEX, 2) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! Get alias name from /ALIAS on command line 
STATUS = CLISGET_ VALUE (‘ALIAS', ALIASNAME) 
! Insert aliases in index 2 until bad return status 
! which indicates end of qualifier values 
DO WHILE (STATUS) 
! Calculate length of alias name 
ALIASNAME LEN = LIBSLOCC (’' ', ALIASNAME) - 1 
! Put alias name in index 
STATUS = LBRSINSERT_KEY (INDEX, 
ALTASNAME (1:ALIASNAME LEN) , 
TXTRFA) 
IF ((.NOT. STATUS) .AND. 
(STATUS .NE. %LOC (LBR$_DUPKEY) ) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 
! Get another alias 
STATUS = CLISGET_VALUE (‘ALIAS’, ALIASNAME) 
END DO 


! Issue warning if module does not exist 

ELSE IF (STATUS .EQ. SLOC (LBRS$ KEYNOTFND)) THEN 
CALL LIBSSIGNAL (DOLIB NOMOD, 

ZVAL (1), 

MODNAME (1:MODNAME_ LEN) ) 


ELSE 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


! Exit 
END 


You can look up a module using any of the keys associated with it. The following 
code fragment checks index 2 for a key if the lookup in the primary index fails: 


STATUS = LBRSSET_ INDEX (INDEX, 1) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
STATUS = LBRSLOOKUP_KEY (INDEX, 
MODNAME (1:MODNAME LEN) , 
TXTRFA) 
IF (STATUS .EQ. sLOC (LBRS$ KEYNOTFND)) THEN 
STATUS = LBRSSET_ INDEX (INDEX, 2) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
STATUS = LBRSLOOKUP_KEY (INDEX, 
MODNAME (1:MODNAME LEN) , 
TXTRFA) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


There are two ways to identify the keys associated with a module: 
e Use the LBR$LOOKUP_KEY routine to look up the module using one of the 
keys. 


« UseLBR$SEARCH to search applicable indexes for the keys. LBR$SEARCH 
calls a user-written routine each time it retrieves a key. The routine must be 
an integer function defined as external that returns a success (odd number) 
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or failure (even number) status. LBR$SEARCH stops processing on a return 
status of failure. 


The subroutine in Example 13-6 lists the names of keys in index 2 (the aliases) 
that point to a module identified on the command line by the module’s name in 
the primary index. 


Example 13-6 Listing Keys Associated with a Module 


SUBROUTINE SHOWAL (INDEX) 
! Lists aliases for a module 


INTEGER STATUS, ! Return status 
INDEX, ! Library index 
TXTRFA (2) ! RFA for module text 


CHARACTER*31 MODNAME ! Name of module 
INTEGER MODNAME LEN ! Length of module name 
! VMS library procedures 
INTEGER LBRSLOOKUP_ KEY, 
LBRSSEARCH, 
LIBSLOCC 
! Return codes 
EXTERNAL LBR$ KEYNOTFND, ! Key not found 
DOLIB NOMOD ! No such module 
! Search routine 
EXTERNAL SEARCH 
INTEGER SEARCH 
! Get module name and calculate length 
CALL CLISGET VALUE (’SHOWALIAS’, MODNAME) 
MODNAME LEN = LIBSLOCC (’ ‘, MODNAME) - 1 
! Look up module in index 1 
STATUS = LBRSLOOKUP_KEY (INDEX, 
MODNAME (1:MODNAME LEN), 
TXTRFA) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! Search for alias names in index 2 
STATUS = LBRSSEARCH (INDEX, 
2; 
TXTRFA, 
SEARCH) 


END 

INTEGER FUNCTION SEARCH (ALIASNAME, RFA) 

! Function called for each alias name pointing to MODNAME 
! Displays the alias name 


INTEGER STATUS OK, ! Good return status 
RFA (2) ! RFA of module 

PARAMETER (STATUS OK = 1) ! Odd number 

CHARACTER* (*) ALIASNAME ! Name of module 


! Display module name 
TYPE *, MODNAME 

! Exit 

SEARCH = STATUS OK 
END 
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13.2.6 Accessing Module Headers 


You can store user information in the header of each module up to the total size 
of the header specified at library creation time in the CRE$L_UHDMAX option. 
The total size of each header in bytes is the value of MHD$B_USRDAT plus the 
value assigned to the CRE$L_UHDMAX option. The value of MHD$B_USRDAT 
is defined by the macro $MHDDEF; the default value is 16 bytes. 


To put user data into a module header, first locate the module with 
LBR$LOOKUP_KEY; then move the data to the module header by invoking 
LBR$SET MODULE, specifying the first argument (index value returned by 
LBR$INI_CONTROL), the second argument (RFA returned by LBR$LOOKUP_ 
KEY), and the fifth argument (character string containing the user data). 


To read user data from a module header, first locate the module with 
LBR$LOOKUP_KEY; then, retrieve the entire module header by invoking 
LBR$SET MODULE, specifying the first, second, third (character string to 
receive the contents of the module header), and fourth (length of the module 
header) arguments. The user data starts at the byte offset defined by MHD$B __ 
USRDAT. Convert this value to a character string subscript by adding 1. 


Example 13-7 displays the user data portion of module headers on SYS$OUTPUT 
and applies updates from SYS$INPUT. 


Example 13-7 Displaying the Module Header 


SUBROUTINE MODHEAD (INDEX) 
! Modifies module headers 


INTEGER STATUS, ! Return status 

INDEX, ! Library index 

TXTRFA (2) ! RFA of module 
CHARACTER*31 MODNAME ! Name of module 
INTEGER MODNAME LEN ! Length of module name 
CHARACTER*80 HEADER ! Module header 
INTEGER HEADER LEN ! Length of module header 
INTEGER USER_START ! Start of user data in header 
CHARACTER*64 USERDATA ! User data part of header 
INTEGER*2 USERDATA LEN ! Length of user data 
! VMS library procedures 
INTEGER LBRSLOOKUP_KEY, 

LBRSSET_ MODULE, 

LIBSGET_INPUT, 

LIBSPUT_ OUTPUT, 
CLISGET VALUE, 
LIBSLOCC 
! Offset to user data --- defined in SMHDDEF 
EXTERNAL MHDS$B USRDAT 
! Return codes 
EXTERNAL LBR$ KEYNOTFND, ! Key not found 
DOLIB_NOMOD ! No such module 
! Calculate start of user data in header 
USER START = %LOC (MHDSB USRDAT) + 1 
! Get module name from /MODHEAD on command line 
STATUS = CLISGET VALUE ('’MODHEAD’, MODNAME) 


(continued on next page) 
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Example 13-7 (Cont.) Displaying the Module Header 


! Get module headers until bad return status 
! which indicates end of qualifier values 
DO WHILE (STATUS) 


! Calculate length of module name 

MODNAME LEN = LIBSLOCC (’ ', MODNAME) - 1 

! Look up module name in library index 

STATUS = LBRSLOOKUP_KEY (INDEX, 
MODNAME (1:MODNAME LEN), 
TXTRFA) 


! Get header if module exists 
IF (STATUS) THEN 
STATUS = LBRSSET MODULE (INDEX, 

TXTRFA, 
HEADER, 
HEADER _LEN) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) 

! Display header and solicit replacement 

STATUS = LIBSPUT_OUTPUT 

‘User data for module '//MODNAME (1:MODNAME LEN) //':’) 

F (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS 

TATUS = LIBSPUT_OUTPUT 

HEADER (USER _START:HEADER LEN) ) 

.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS 

'ATUS = LIBSPUT OUTPUT 


F 

‘Enter replacement text below or just hit return:’) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS 
F 


'ATUS = LIBSGET_INPUT (USERDATA,, USERDATA_ LEN) 
.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS 
! Replace user data 
IF (USERDATA LEN .GT. 0) THEN 

STATUS = LBRSSET MODULE (INDEX, 

TXTRFA, ,, 

USERDATA (1:USERDATA LEN) ) 


END IF 


! Issue warning if module does not exist 
ELSE IF (STATUS .EQ. %LOC (LBRS$ KEYNOTFND)) THEN 
CALL LIBSSIGNAL (DOLIB NOMOD, 
SVAL (1), 
MODNAME (1:MODNAME_ LEN) ) 


ELSE 
CALL LIBSSIGNAL (SVAL (STATUS) ) 
END IF 


! Get another module name 
STATUS = CLISGET_VALUE (‘MODHEAD’ , MODNAME) 
END DO 


! Exit 
END 


13.2.7 Reading Library Headers 


Call LBR$GET_HEADER to obtain general information concerning the library. 
Pass the value returned by LBR$INI_CONTROL as the first argument. 
LBR$GET_ HEADER returns the information to the second argument, which 
must be an array of 128 longwords. The LHI symbols identify the significant 
longwords of the array by their byte offsets into the array. Convert these values 
to subscripts by dividing by 4 and adding 1. 
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Example 13-8 reads the library header and displays some information from it. 


Example 13-8 Reading Library Headers 


SUBROUTINE TYPEINFO (INDEX) 
! Types the type, major ID, and minor ID 
! of a library to SYSSOUTPUT 


INTEGER STATUS Return status 


| 
INDEX, ! Library index 
HEADER (128), ! Structure for header information 
TYPE, ! Subscripts for header structure 
MAJOR_ID, 
MINOR_ID 


CHARACTER*8 MAJOR ID TEXT, ! Display info in character format 
MINOR_ID TEXT 

! VMS library procedures 

INTEGER LBRSGET HEADER, 

LIBSPUT_OUTPUT 

! Offsets for header --- defined in SLHIDEF 

EXTERNAL LHISL TYPE, 

LHISL MAJORID, 

LHISL MINORID 

! Library type values --- defined in $LBRDEF 

EXTERNAL LBRSC_TYP OBJ, 

LBRSC_TYP MLB, 

LBRSC_TYP HLP, 

LBRS$C_TYP TXT 

! Get header information 

STATUS = LBRSGET HEADER (INDEX, HEADER) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 

! Calculate subscripts for header structure 

TYPE = SLOC (LHISL TYPE) / 4 +1 

MAJOR_ID = %LOC (LHIS$L MAJORID) / 

MINOR_ID = %LOC (LHISL MINORID) / 

! Display library type 

IF (HEADER (TYPE) .EQ. %LOC (LBRSC_TYP OBJ)) THEN 

STATUS = LIBSPUT OUTPUT ('Library type: object’) 

ELSE IF (HEADER (TYPE) .EQ. %LOC (LBRS$C_TYP MLB)) THEN 

STATUS = LIBSPUT_ OUTPUT (‘Library type: macro’) 

ELSE IF (HEADER (TYPE) .EQ. %LOC (LBRSC_TYP_HLP)) THEN 

STATUS = LIBSPUT OUTPUT (‘Library type: help’) 

ELSE IF (HEADER (TYPE) .EQ. %LOC (LBRSC_TYP_TXT)) THEN 

STATUS = LIBSPUT_OUTPUT ('Library type: text’) 

ELSE 

STATUS = LIBSPUT_OUTPUT 

END IF 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 

! Convert and display major ID 

WRITE (UNIT=MAJOR_ID TEXT, 

FMT='(I)’) HEADER (MAJOR_ID 

STATUS = LIBSPUT OUTPUT ('’Major ID: ‘'//MAJOR_ID TEXT) 

IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 

! Convert and display minor ID 

WRITE (UNIT=MINOR_ID TEXT, 

FMT='(I)’) HEADER (MINOR_ID 

STATUS = LIBSPUT OUTPUT (’Minor ID: '//MINOR ID TEXT) 


IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 


44+ 1 
441 


Library type: unknown’ 


(continued on next page) 
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Example 13-8 (Cont.) Reading Library Headers 


! Exit 
END 


13.2.8 Displaying Help Text 


You can display text from a help library by calling the LBR$OUTPUT HELP 
routine and specifying the output routine, the keywords, and the name of the 
library. You must also specify the input routine if the prompting mode flag is set 
or if the flags argument is omitted. 


Note 


If you specify subprograms in an argument list, they must be declared as 
external. 


You can use the LIB$PUT_OUTPUT and LIB$GET_INPUT routines to specify 
the output routine and the input routine. (If you use your own routines, 
make sure the argument lists are the same as for LIB$PUT OUTPUT and 
LIB$GET_INPUT.) Do not call LBR$INI_CONTROL and LBR$OPEN before 
calling LBRS$OUTPUT_HELP. 


Example 13-9 solicits keywords from SYS$INPUT and displays the text 
associated with those keywords on SYS$OUTPUT, thus inhibiting the prompting 
facility. 


Example 13-9 Displaying Text from a Help Library 


PROGRAM GET HELP 


! Prints help text from a help library 
CHARACTER*31 LIBSPEC Library name 
CHARACTER*15 KEYWORD Keyword in help library 
INTEGER*2 LIBSPEC LEN, Length of name 
KEYWORD LEN Length of keyword 
INTEGER FLAGS, Help flags 

STATUS Return status 

! VMS library procedures 

INTEGER LBRSOUTPUT_ HELP, 

IBSGET_INPUT, 

IBSPUT_OUTPUT 

IBSGET_ INPUT, 

IBSPUT_OUTPUT 

! Error codes 


(ell es! 


EXTERNAL 


Ee ES 


EXTERNAL RMS$_EOF, ! End-of-file 
LIBS _INPSTRTRU ! Input string truncated 
! Flag values --- defined in SHLPDEF 


EXTERNAL HLPSM PROMPT, 
LPSM_ PROCESS, 
LPSM_ GROUP, 
LPSM SYSTEM, 
LPSM LIBLIST, 
LPSM HELP 


aoe 


(continued on next page) 
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Example 13-9 (Cont.) Displaying Text from a Help Library 


! Get library name 
STATUS = LIBSGET_INPUT (LIBSPEC, 
‘Library: ', 
LIBSPEC_LEN) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
IF (LIBSPEC_LEN .EQ. 0) THEN 
LIBSPEC = ‘'HELPLIB’ 
LIBSPEC LEN = 7 
END IF 
! Set flags for no prompting 
FLAGS = %LOC (HLP$ PROCESS) + 
SLOC (HLPS GROUP) + 
SLOC (HLPS SYSTEM) 


! Get first keyword 
STATUS = LIBSGET_INPUT (KEYWORD, 
‘Keyword or Ctrl/Z: ', 
KEYWORD _LEN) 
IF ((.NOT. STATUS) .AND. 
(STATUS .NE. %LOC (LIBS INPSTRTRU)) .AND. 
(STATUS .NE. %LOC (RMS$ EOF))) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 
! Display text until end-of-file 
DO WHILE (STATUS .NE. %LOC (RMSS$ EOF) ) 
STATUS = LBRSOUTPUT_HELP (LIBSPUT OUTPUT,, 
KEYWORD (1:KEYWORD LEN), 
LIBSPEC (1:LIBSPEC_ LEN), 
FLAGS , 
LIBSGET_INPUT) 
IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 
! Get another keyword 
STATUS = LIBSGET_INPUT (KEYWORD, 
‘Keyword or Ctrl/Z: ', 
KEYWORD LEN) 
IF ((.NOT. STATUS) .AND. 
(STATUS .NE. %LOC (LIBS INPSTRTRU)) .AND. 
(STATUS .NE. SLOC (RMS$ EOF))) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 
END DO 


! Exit 
END 


13.2.9 Listing and Processing Index Entries 


You can process index entries an entry at a time by invoking LBR$GET_INDEX. 
The fourth argument specifies a match name for the entry or entries in the index 
to be processed: you can include the asterisk (*) and percent (%) characters in 
the match name for generic processing. For example, MOD* means all entries 
whose names begin with MOD; and MOD% means all entries whose names are 
four characters and begin with MOD. 


The third argument names a user-written routine that is executed once for each 
index entry specified by the fourth argument. The routine must be a function 
declared as external that returns a success (odd number) or failure (even number) 
status. LBR$GET_INDEX processing stops on a return status of failure. Declare 
the first argument passed to the function as a passed-length character argument; 
this argument contains the name of the index entry. Declare the second argument 
as an integer array of two elements. 
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Example 13-10 obtains a match name from the command line and displays the 
names of the matching entries from index 1 (the index containing the names of 
the modules). 


Example 13-10 Displaying Index Entries 


SUBROUTINE LIST (INDEX) 
! Lists modules in the library 


INTEGER STATUS, ! Return status 

INDEX, ! Library index 
CHARACTER*31 MATCHNAME ! Name of module to list 
INTEGER MATCHNAME LEN ! Length of match name 

! VMS library procedures 

INTEGER address LBRSGET INDEX, 

LIBSLOCC 

! Match routine 

INTEGER MATCH 

EXTERNAL MATCH 

! Get module name and calculate length 

CALL CLISGET VALUE (‘LIST’, MATCHNAME) 
MATCHNAME LEN = LIBSLOCC ('’ ', MATCHNAME) - 1 

! Call routine to display module names 

STATUS = LBRSGET_INDEX (INDEX, 

1, ! Primary index 
MATCH, 

MATCHNAME (1:MATCHNAME LEN) ) 


IF (.NOT. STATUS) CALL LIBSSIGNAL (%VAL (STATUS) ) 


! Exit 
END 
INTEGER FUNCTION MATCH (MODNAME, RFA) 

! Function called for each module matched by MATCHNAME 
! Displays the module name 


INTEGER STATUS OK, ! Good return status 

RFA (2) ! RFA of module name in index 
PARAMETER (STATUS_OK = 1) ! Odd value 
CHARACTER* (*) MODNAME ! Name of module 


! Display the name 
TYPE *, MODNAME ! Display module name 


! Exit 
MATCH = STATUS OK 
END 


13.3 LBR Routines 


This section describes the individual LBR routines. 
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LBR$CLOSE—Close a Library 


Format 


Returns 


Argument 


Description 


The LBR$CLOSE routine closes an open library. 


LBR$CLOSE _library_index 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


When you are finished working with a library, you should call LBR$CLOSE to 
close it. Upon successful completion, LBR$CLOSE closes the open library and 
deallocates all of the memory used for processing it. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$DELETE_DATA—Delete Module Data from the Library 


Format 


Returns 


Arguments 


The LBR$DELETE_DATA routine deletes module data from the library. 


LBR$DELETE_DATA library_index, txtrfa [,flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


txtrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Record’s file address (RFA) of the module header for the module you want to 
delete. The txtrfa argument is the address of the 2-longword array that contains 
the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_ 
KEY or LBR$PUT_RECORD. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by value 


The contents of the flag are ignored. The purpose of this argument is to indicate 
to this routine that the application knows about the new index structure for ELF 
object and ELF shareable image libraries. 
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Description 


To delete a library module, first call LBR$DELETE KEY to delete all keys 
that point to it. If no library index keys are pointing to the module header, 
LBR$DELETE_DATA deletes the module header and associated data records; 
otherwise, this routine returns the error LBR$ STILLKEYS. 


Note that other library routines can reuse data blocks that contain no data. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 

LBR$ INVRFA Specified RFA not valid. 

LBR$ LIBNOTOPN Specified library not open. 

LBR$ STILLKEYS Keys in other indexes still point to the module 
header. Therefore, the specified module was not 
deleted. 
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LBR$DELETE_KEY—Delete a Key 


The LBR$DELETE_KEY routine removes a key from the current library index. 


Format 
LBR$DELETE_KEY _library_index, key_name|, txtrfa] [, flags] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
library_index 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of a longword that contains the index. 


key_name 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The key to be deleted from the library index. For libraries with binary keys, the 
key_name argument is the address of an unsigned longword containing the key 
number. 


For libraries with ASCII keys, the key_name argument is the address of the 
string descriptor pointing to the key with the following argument characteristics: 


Argument Characteristics Entry 


OpenVMS usage char_string 

type character string 
access read only 
mechanism by descriptor 
txtrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 
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The txtrfa argument is the address of the 2-longword array that contains the 
record file address (RFA). If present and if the flags argument is not present, 
the routine scans for all types of the key for the specified txtrfa and delete those 


entries. 

flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by value 


If present, this argument indicates that a particular type of the key or all types 
of the key is to be deleted. The flags bits are as follows: 


Flag Bits Description 

LBR$M_SYM_WEAK =0x1 UNIX-style weak symbol attribute 
LBR$M_SYM_GROUP =0x2 Group symbol attribute 
LBR$M_SYM_ALL = All symbols 

0x80000000 


If the txtrfa argument is not present or if its value is zero, the type indicated 
by flags is deleted. If txtrfa specifies a nonzero value, the entry of the type 
indicated, with the txtrfa supplied, is removed. Note that only one type or all 
types can be specified. 


Description 


If LBR$DELETE_KEY finds the key specified by key_name in the current 
index, it deletes the key. Note that if you want to delete a library module, you 
should first use LBR$DELETE_KEY to delete all keys that point to it, then use 
LBR$DELETE_DATA to delete the module's header and associated data. You 
cannot call LBR$DELETE_ KEY from within the user-supplied routine specified 
in LBR$SEARCH or LBR$GET_INDEX. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ KEYNOTFND Specified key not found. 

LBR$ LIBNOTOPN Specified library not open. 

LBR$ UPDIRTRAV Specified index update not valid in a user- 


supplied routine specified in LBR$SEARCH 
or LBR$GET_INDEX. 
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LBR$FIND—Look Up a Module by Its RFA 


The LBR$FIND routine sets the current internal read context for the library to 
the library module specified. 


Format 
LBR$FIND  library_index ,txtrfa 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
library_index 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 
txtrfa 
OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Record’s file address (RFA) of the module header for the module you want to 
access. The txtrfa argument is the address of a 2-longword array containing the 
RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_KEY 
or LBR$PUT_RECORD. 
Description 


Use the LBR$FIND routine to access a module that you had accessed earlier in 
your program. For example, if you look up several keys with LBR$LOOKUP_ 
KEY, you can save the RFAs returned by LBR$LOOKUP_KEY and later use 
LBR$FIND to reaccess the modules. Thus, you do not have to look up the module 
header’s key every time you want to access the module. If the specified RFA is 
valid, LBR$FIND initializes internal tables so you can read the associated data. 
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Condition Values Returned 
LBR$ ILLCTL Specified library control index not valid. 
LBR$ INVRFA Specified RFA not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$FLUSH—Recover Virtual Memory 


The LBR$FLUSH routine writes modified blocks back to the library file and frees 
the virtual memory the blocks had been using. 


Format 
LBR$FLUSH _library_index ,block_type 

Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 
library_index 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 
block_type 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by value 
Extent of the flush operation. The block_type argument contains the longword 
value that indicates how the flush operation proceeds. If you specify LBR$C_ 
FLUSHDATA, the data blocks are flushed. If you specify LBR$C_FLUSHALL, 
first the data blocks and then the current library index are flushed. 
Each programming language provides an appropriate mechanism for accessing 
these symbols. 

Description 


LBR$FLUSH cannot be called from other LBR routines that reference cache 
addresses or by routines called by LBR routines. 
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Condition Values Returned 

LBR$ NORMAL Operation completed successfully. 

LBR$ BADPARAM Error. A value passed to the LBR$FLUSH 
routine was either out of range or an illegal 
value. 

LBR$ WRITERR Error. An error occurred during the writing of 


the cached update blocks to the library file. 
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LBR$GET_HEADER—Retrieve Library Header Information 


The LBR$GET_HEADER routine returns information from the library’s header to 


the caller. 
Format 
LBR$GET_HEADER library_index ,retary 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
library_index 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


retary 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


Array of 128 longwords that receives the library header. The retary argument is 
the address of the array that contains the header information. The information 
returned in the array is listed in the following table. Each programming language 
provides an appropriate mechanism for accessing this information. 


Offset in 

Longwords Symbolic Name Contents 
6) LHI$L_TYPE Library type (see LBR$OPEN for 

possible values) 

1 LHI$L_NINDEX Number of indexes 
2 LHI$L_MAJ ORID Library format major identification 
3 LHI$L_MINORID Library format minor identification 
4 LHI$T LBRVER ASCIC version of Librarian 

12 LHI$L_CREDAT Creation date/time 

14 LHI$L_UPDTIM Date/time of last update 


LBR-38 Librarian (LBR) Routines 


Librarian (LBR) Routines 
LBR$GET_HEADER 


Offset in 
Longwords 


Symbolic Name 


Contents 


16 


17 
18 
19 


21 
22 


23 
24 
25 
26 
27 


28 


29 


30 


31 


32-128 


LHI$L_UPDHIS 


LHI$L_FREEVBN 
LHI$L_FREEBLK 
LHI$B_NEXTRFA 


LHI$L_NEXTVBN 
LHI$L_FREIDXBLK 


LHI$L_FREEIDX 
LHI$L_HIPREAL 
LHI$L_IDXBLKS 
LHI$L_IDXCNT 

LHI$L_MODCNT 


LHI$L_MHDUSZ 
LHI$L_MAXLUHREC 
LHI$L_NUMLUHREC 


LHI$L_LIBSTATUS 


Virtual block number (VBN) of start of 
update history 


First logically deleted block 
Number of deleted blocks 


Record file address (RFA) of end of 
library 


Next VBN to allocate at end of file 


Number of free preallocated index 
blocks 


List head for preallocated index blocks 
VBN of highest preallocated block 
Number of index blocks in use 
Number of index entries (total ) 
Number of entries in index 1 (module 
names) 

Number of bytes of additional 
information reserved in module header 
Maximum number of library update 
history records maintained 

Number of library update history 
records in history 

Library status (false if there was an 
error closing the library) 

Reserved by HP 


Description 


On successful completion, LBR$GET HEADER places the library header 
information into the array of 128 longwords. 


Note that the offset is the byte offset of the value into the header structure. You 
can convert the offset to a longword subscript by dividing the offset by 4 and 
adding 1 (assuming that subscripts in your programming language begin with 1). 


Condition Values Returned 


LBR$ ILLCTL 
LBR$ LIBNOTOPN 


Specified library control index not valid. 


Specified library not open. 
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LBR$GET_HELP—Retrieve Help Text 


Format 


Returns 


Arguments 


The LBR$GET_HELP routine retrieves help text from a help library, displaying 
it on SYS$OUTPUT or calling your routine for each record returned. 


LBR$GET_HELP _library_index [,line_width] [,routine] [,data] [,key_1] 
[, key_2... ,key_10] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


line_width 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: read only 
mechanism: by reference 


Width of the help text line. The line_width argument is the address of a 
longword containing the width of the listing line If you do not supply a line 
width or if you specify 0, the line width defaults to 80 characters per line 


routine 

OpenVMS usage: procedure 

type: procedure value 
access: read only 
mechanism: by reference 


Routine called for each line of text you want output. The routine argument is 
the address of the procedure value for this user-written routine. 


If you do not supply a routine argument, LBR$GET_ HELP calls the Run-Time 
Library procedure LIB$PUT OUTPUT to send the help text lines to the current 
output device (SY S$OUTPUT). However, if you want SYS$OUTPUT for your 
program to be a disk file rather than the terminal, you should supply a routine to 
output the text. 
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If the user-written routine returns an error status with low bit clear, the 
LBR$GET_HELP routine passes this status to the caller. If the user-written 
routine returns a success status with low bit set, the LBR$GET_HELP routine 
returns 1 to the caller. 


The routine you specify is called with an argument list of four longwords: 
1. The first argument is the address of a string descriptor for the output line. 


2. Thesecond argument is the address of an unsigned longword containing flag 
bits that describe the contents of the text being passed. The possible flags are 
as follows: 

HLP$M_NOHLPTXT Specified help text cannot be found. 

HLP$M_KEYNAMLIN _ Text contains key names of the printed text. 

HLP$M_OTHERINFO Text is part of the information provided on 
additional help available. 


Each programming language provides an appropriate mechanism for 
accessing these flags. Note that, if no flag bit is set, help text is passed. 


3. Thethird argument is the address stipulated in the data argument specified 
in the call to LBR$GET_HELP (or the address of a 0 constant if the data 
argument is zero or was omitted). 


4. The fourth argument is a longword containing the address of the current key 
level. 


The routine you specify must return with success or failure status. A failure 
status (low bit =0) terminates the current call to LBR$GET_HELP. 


data 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Data passed to the routine specified in the routine argument. The data 
argument is the address of data for the routine. The address is passed to the 
routine specified in the routine argument. If you omit this argument or specify 
it as zero, then the argument passed in your routine will be the address of a zero 
constant. 


key_1,key_2, ... ,key_10 
OpenVMS usage: longword_signed 


type: longword (signed) 
access: read only 
mechanism: by descriptor 


Level of the help text to be output. Each key_1,key_2, ... ,key_10 argument is 
the address of a descriptor pointing to the key for that level. 


If the key_1 descriptor is 0 or if it is not present, LBR$GET HELP assumes 
that the key_1 name is HELP, and it ignores all the other keys. For key_2 
through key_10, a descriptor address of 0, or a length of 0, or a string address of 
0 terminates the list. 
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The key argument may contain any of the following special character strings: 


String Meaning 

i Return all level 1 help text in the library. 

KEY... Return all help text associated with the specified key and its subkeys 
(valid for level 1 keys only). 

are Return all help text in the library. 


Description 


LBR$GET_HELP returns all help text in the same format as the output returned 
by the DCL command HELP; that is, it indents two spaces for every key level 

of text displayed. (Because of this formatting, you may want to make your help 
messages shorter than 80 characters, so they fit on one line on terminal screens 
with the width set to 80.) If you do not want the help text indented to the 
appropriate help level, you must supply your own routine to change the format. 


Note that most application programs use LBR$OUTPUT_HELP instead of 
LBR$GET_HELP. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 
LBR$ NOTHLPLIB Specified library not a help library. 
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LBR$GET_HISTORY—Retrieve a Library Update History Record 


Format 


Returns 


Arguments 


Description 


The LBR$GET_HISTORY routine returns each library update history record toa 
user-specified action routine. 


LBR$GET_HISTORY _ library_index ,action_routine 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


action_routine 
OpenVMS usage: procedure 


type: procedure value 
access: modify 
mechanism: by reference 


User-supplied routine for processing library update history records. The action_ 
routine argument is the address of the procedure value of this user-supplied 
routine. The routine is invoked once for each update history record in the library. 
One argument is passed to the routine, namely, the address of a descriptor 
pointing to a history record. 


This routine retrieves the library update history records written by the routine 
LBR$PUT_HISTORY. 
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Condition Values Returned 


LBR$ NORMAL 
LBR$ EMPTYHIST 


LBR$ INTRNLERR 
LBR$ NOHISTORY 
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Normal exit from the routine. 


History empty. This is an informational code, not 
an error code. 


Internal Librarian routine error occurred. 


No update history. This is an informational code, 
not an error code. 
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LBR$GET_INDEX—Call a Routine for Selected Index Keys 


Format 


Returns 


Arguments 


The LBR$GET_INDEX routine calls a user-supplied routine for selected keys in 
an index. 


LBR$GET_INDEX  library_index ,index_number ,routine_name [,match_desc] [, 
flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


index_number 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Number of the library index. The index_number argument is the address of a 
longword containing the index number. This is the index number associated with 
the keys you want to use as input to the user-supplied routine. 


routine_name 
OpenVMS usage: procedure 


type: procedure value 
access: read only 
mechanism: by reference 


User-supplied routine called for each of the specified index keys. The routine_ 
name argument is the address of the procedure value for this user-supplied 
routine. 
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LBR$GET_INDEX passes two arguments to the routine: 
e A key name. 


- For libraries with ASCII keys, the key_name argument is the address of 
a string descriptor pointing to the key. Note that the string and the string 
descriptor passed to the routine are valid only for the duration of that 
call. The string must be copied privately if you need it again for more 
processing. 


- For libraries with binary keys, the key_name argument is the address of 
an unsigned longword containing the key number. 


e« The record file address (RFA) of the module’s header for this key name. The 
RFA argument is the address of a 2-longword array that contains the RFA. 


e The key’s type whose bits are as follows: 


Flag Bits Description 
LBR$M_SYM_WEAK =1 UNIX-style weak symbol attributes 
LBR$M_SYM_GROUP =2 Group symbol attribute 


The user routine must return a value to indicate success or failure. If the user 
routine returns a false value (low bit =0), LBR$GET_INDEX stops searching 
the index and returns the status value of the user-specified routine to the calling 


program. 

The routine cannot contain calls to either LBR$DELETE_KEY or LBR$INSERT_ 
KEY. 

match_desc 

OpenVMS usage: char_string 

type: character string 

access: read only 

mechanism: by descriptor 


Key matching identifier. The match_desc argument is the address of a string 
descriptor pointing to a string used to identify which keys result in calls to the 
user-supplied routine. Wildcard characters are allowed in this string. If you omit 
this argument, the routine is called for every key in the index. The match_desc 
argument is valid only for libraries that have ASCII keys. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by value 


If present and non-zero, this argument specifies the type, or all types, of the key 
provided. The flag bits are: 


Flag Bits Description 
LBR$M_SYM_WEAK =Ox1 UNIX-style weak symbol attribute 
LBR$M_SYM_GROUP =0x2 Group symbol attribute 
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Flag Bits Description 
LBR$M_SYM_ALL =0x80000000 All symbols 
The user routine will be provided the key’s type through an additional third 
parameter. 
Description 


LBR$GET_INDEX searches through the specified index for keys that match the 
match_desc argument. Each time it finds a match, it calls the user routine 
specified by the routine_name argument. If you do not specify the match_desc 
argument, LBR$GET_INDEX calls the user routine for every key in the index. 


For example, if you call LBR$GET_INDEX on an object library with match_desc 
equal to TR* and index_number set to 1 (module name table), then LBR$GET_ 
INDEX calls routine_name for each module whose name begins with TR. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR¢ ILLIDXNUM Specified index number not valid. 
LBR$ LIBNOTOPN Specified library not open. 

LBR$ NULIDX Specified library empty. 
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LBR$GET_RECORD—Read a Data Record 


Format 


Returns 


Arguments 


The LBR$GET_RECORD routine returns the next data record in the module 
associated with a specified key. 


LBR$GET_RECORD _library_index [,inbufdes] [,outbufdes] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. The 
library must be open and LBR$LOOKUP_KEY or LBR$FIND must have been 
called to find the key associated with the module whose records you want to read. 


inbufdes 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


User buffer to receive the record. The inbufdes argument is the address 

of a string descriptor that points to the buffer that receives the record from 
LBR$GET_ RECORD. This argument is required when the Librarian subroutine 
record access is set to move mode (which is the default). This argument is not 
used if the record access mode is set to locate mode. The Description section 
contains more information about the locate and move modes. 


outbufdes 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


String descriptor that receives the actual length and address of the data for the 
record returned. The outbufdes argument is the address of the string descriptor 
for the returned record. The length and address fields of the string descriptor are 
filled in by the LBR$GET_ RECORD routine. This parameter must be specified 
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when Librarian subroutine record access is set to locate mode. This parameter 
is optional if record access mode is set to move mode. The Description section 
contains more information about the locate and move modes. 


Description 


Before calling LBR$GET RECORD, you must first call LBR$LOOKUP_KEY or 
LBR$FIND to set the internal library read context to the record's file address 
(RFA) of the module header of the module whose records you want to read. 


LBR$GET RECORD uses two record access modes: locate mode and move 
mode. Move mode is the default. The LBR$SET_LOCATE and LBR$SET_MOVE 
subroutines set these modes. The record access modes are mutually exclusive; 
that is, when one is set, the other is turned off. If move mode is set, LBR$GET_ 
RECORD copies the record to the user-specified buffer described by inbufdes. If 
you have optionally specified the output buffer string descriptor, outbufdes, the 
Librarian fills it with the actual length and address of the data. If locate mode 
is set, LBR$GET RECORD returns the record by way of an internal subroutine 
buffer, pointing the outbufdes descriptor to the internal buffer. The second 
parameter, inbufdes, is not used when locate mode is set. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 

LBR$ LKPNOTDON Requested key lookup not done. 

RMS$ EOF Error. An attempt has been made to read past 


the logical end of the data in the module. 
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LBR$INI_CONTROL—Initialize a Library Control Structure 


The LBR$INI_CONTROL routine initializes a control structure, called a library 
control index, to identify the library for use by other LBR routines. 


Format 
LBR$INI_CONTROL  library_index ,func [,type] [,namblk] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
library_index 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of a longword that is to receive the index. 


func 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library function to be performed. The func argument is the address of the 
longword that contains the library function. Valid functions are LBR$C_CREATE, 
LBR$C_READ, and LBR$C_UPDATE. Each programming language provides an 
appropriate mechanism for accessing these symbols. 


type 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library type. The type argument is the address of the longword containing the 
library type. Valid library types include the following: 


* LBR$C_TYP_OBJ (VAX object) 

e LBR$C_TYP_SHSTB (VAX shareable image) 

* LBR$C_TYP_EOB} (Alpha object) 

e LBR$C_TYP_ESHSTB (Alpha shareable image) 
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e LBR$C_TYP_MLB (macro) 

e LBR$C_TYP_HLP (help) 

* LBR$C_TYP_TXT (text) 

e LBR$C_TYP_UNK (unknown) 

e LBR$C_TYP_NCS (NCS library) 


e For user-developed libraries, a type in the range of LBR$C_TYP_USRLW 
through LBR$C_TYP_USRHI. 


namblk 

OpenVMS usage: nam 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


OpenVMS RMS name block (NAM). The namblk argument is the address of a 
variable-length data structure containing an RMS NAM block. The LBR$OPEN 
routine fills in the information in the NAM block so it can be used later to open 
the library. If the NAM block has this file identification in it from previous use, 
the LBR$OPEN routine uses the open-by-NAM block option. This argument is 
optional and should be used if the library will be opened many times during a 
single run of the program. For a detailed description of RMS NAM blocks, see the 
OpenVMS Record Management Services Reference M anual. 


Except for the LBR$OUTPUT_HELP routine, you must call LBR$INI_CONTROL 
before calling any other LBR routine. After you initialize the library control 
index, you must open the library or create a new one using the LBR$OPEN 
routine. You can then call other LBR routines that you need. After you finish 
working with a library, close it with the LBR$CLOSE routine. 


LBR$INI_CONTROL initializes a library by filling the longword referenced by the 
library_index argument with the control index of the library. Upon completion 
of the call, the index can be used to refer to the current library in all future 
routine calls. Therefore, your program must not alter this value. 


You can have up to 16 libraries open simultaneously in your program. 


Condition Values Returned 


LBR$ NORMAL Library control index initialized successfully. 
LBR$ ILLFUNC Requested function not valid. 

LBR¢ ILLTYP Specified library type not valid. 

LBR$ TOOMNYLIB Error. An attempt was made to allocate more 


than 16 control indexes. 
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LBR$INSERT_KEY—Insert a New Key 


Format 


Returns 


Arguments 


The LBR$INSERT_KEY routine inserts a new key in the current library index. 


LBR$INSERT_KEY _ library_index ,key_name ,txtrfa [, flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL library routine. The 
library_index argument is the address of the longword that contains the index. 


key_name 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Name of the new key you are inserting. 


If the library uses binary keys, the key_name argument is the address of an 
unsigned longword containing the value of the key. 


If the library uses ASCII keys, the key_name argument is the address of a string 
descriptor of the key with the following argument characteristics: 


Argument 

Characteristics Entry 

OpenVMS usage char_string 
type character string 
access read only 
mechanism by descriptor 
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txtrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: modify 

mechanism: by reference 


The record file address (RFA) of the module associated with the new key you are 
inserting. The txtrfa argument is the address of a 2-longword array containing 
the RFA. You can use the RFA returned by the first call to LBR$PUT RECORD. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by value 


If present, specifies the key’s type. The flag bits are as follows: 


Flag Bits Description 
LBR$M_SYM_WEAK =0x1 UNIX-style weak symbol attribute 
LBR$M_SYM_GROUP =0x2 Group symbol attribute 
If this argument is not present, the normal NonGroup-Global type is the assumed 
type. 

Description 


The LBR$INSERT_KEY routine inserts a new key in the current library index. 
You cannot call LBR$INSERT_KEY within the user-supplied routine specified in 
LBR$SEARCH or LBR$GET_INDEX. 


Condition Values Returned 


LBR$ DUPKEY Index already contains the specified key. 
LBR$ ILLCTL Specified library control index not valid. 
LBR$ INVRFA Specified RFA does not point to valid data. 
LBR$ LIBNOTOPN Specified library not open. 

LBR$ UPDURTRAV LBR$INSERT_KEY was called by the user- 


defined routine specified in LBR$SEARCH or 
LBR$GET_INDEX. 
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LBR$LOOKUP_KEY—Look Up a Library Key 


Format 


Returns 


Arguments 


The LBR$LOOKUP_KEY routine looks up a key in the library's current index 
and prepares to access the data in the module associated with the key. 


LBR$LOOKUP_KEY _ library_index ,key_name ,txtrfa [, flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


key_name 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Name of the library key. If the library uses binary keys, the key_name argument 
is the address of the unsigned longword value of the key. 


If the library uses ASCII keys, the key_name argument is the address of a string 
descriptor for the key with the following argument characteristics: 


Argument Characteristics Entry 

OpenVMS usage char_string 
type character string 
access read only 
mechanism by descriptor 
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txtrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


The record file address (RFA) of the library module header. The txtrfa argument 
is the address of the 2-longword array that receives the RFA of the module 


header. 

flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


The flags argument, if present and not zero, receives the type of key returned. 
the flag bits are as follows: 


Flag Bits Description 
LBR$SYM_WEAK =0x1 UNIX-style weak symbol attribute 
LBR$SYM_GROUP =0x2 Group symbol attribute 


The key returned is the highest precedent definition type present. 


Description 


If LBR$LOOKUP_KEY finds the specified key, it initializes internal tables so you 
can access the associated data. 


This routine returns the RFA to the 2-longword array referenced by txtrfa. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ INVRFA RFA obtained not valid. 

LBR$ KEYNOTFND Specified key not found. 

LBR$ LIBNOTOPN Specified library not open. 
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LBR$LOOKUP_TYPE—Searches index and returns key type for the 
module 


The LBR$LOOK_TYPE routine searches the index for the key from a particular 
module (RFA) and returns that key’s type for that module. 


Format 

LBR$LOOKUP_TYPE _library_index, key_name, txtrfa, ret_types 
Arguments 

library_index 

OpenVMS usage: longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


key_name 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The key_name argument is the address of the string descriptor pointing to the 
key with the following argument characteristics: 


Argument Characteristics Entry 

OpenVMS usage char_string 
type character string 
access read only 
mechanism by descriptor 
txtrfa 

OpenVMS usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference 


The module's record file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array that specifies the RFA of the 
module header. 


ret_types 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


The address of a longword to receive the symbol types found for the specified 
module (txtrfa). The return type bits are as follows: 
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LBR$M_SYM_NGG =1 
LBR$M_SYM_UXWK =2 
LBR$M_SYM_GG =4 
LBR$M_SYM_GUXWK =8 


Description 


This routine searches the index for the key from a particular module (RFA) and 
returns that key’s type for that module, if present. Otherwise, it returns LBR$_ 
KEYNOTEFND. 
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LBR$MAP_MODULE—Maps a module into process P2 space (164 


Format 


Arguments 


only) 


The LBR$MAP_MODULE routine maps a module into process P2 space. 


LBR$MAP_MODULE library_index, ret_va_addr, ret_mod_len, txtrfa 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL library routine. The 
library_index argument is the address of the longword that contains the index. 


ret_va_addr 

OpenVMS usage: address 

type: quadword address 

access: write only 

mechanism: by 32-bit or 64-bit reference 


The 32-bit or 64-bit virtual address of a naturally aligned quadword into which 
the routine returns the virtual address at which the routine mapped the library 
module. 


ret_mod_len 
OpenVMS usage: byte count 


type: quadword (unsigned) 
access: read only 
mechanism: by reference 


The address of a naturally aligned quadword into which the library routine 
returns the module length. 


txtrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


The module's record file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array that specifies the RFA of the 
module header. 
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This routine maps a module, with the given txtrfa, into process P2 memory space 


and returns the virtual address where the module is mapped and the module 
size. 


Unlike other LBR services that use RMS services, LBR$MAP_MODULE also uses 
system services. Because of this, the secondary status for error returns is placed 
in LBR$$GL_SUBSTS. Use this secondary status to find additional status when 
an error is returned. 
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LBRSOPEN—Open or Create a Library 


Format 


Returns 


Arguments 


The LBR$OPEN routine opens an existing library or creates a new one. 


LBR$OPEN _library_index [,fns] [,create_options] [,dns] [,rlfna] [,rns] [,rnslen] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of a longword containing the index. 


fns 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


File specification of the library. The fns argument is the address of a string 
descriptor pointing to the file specification. Unless the OpenVMS RMS NAM 
block address was previously supplied in the LBR$INI_ CONTROL routine and 
contained a file specification, this argument must be included. Otherwise, the 
Librarian returns an error (LBR$ NOFILNAM). 


create_options 
OpenVMS usage: vector_longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library characteristics. The create_options argument is the address of an array 
of 20 longwords that define the characteristics of the library you are creating. If 
you are creating a library with LBR$C_CREATE, you must include the create_ 
options argument. The following table shows the entries that the array must 
contain. Each programming language provides an appropriate mechanism for 
accessing the listed symbols. 
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Offset in 
Longwords Symbolic Name Contents 
0 CRE$L_TYPE Library type: 
LBR$C_TYP_UNK (0) Unknown/unspecified 
LBR$C_TYP_OB} (1) VAX object 
LBR$C_TYP_MLB (2) Macro 
LBR$C_TYP_HLP (3) Help 
LBR$C_TYP_TXT (4) Text 
LBR$C_TYP_SHSTB (5) VAX shareable image 
LBR$C_TYP_NCS (6) NCS 
LBR$C_TYP_EOB} (7) Alpha object 
LBR$C_TYP_ESHSTB (8) Alpha shareable image 
(9-127) Reserved by HP 
LBR$C_TYP_USRLW (128) User library types — low 
end of range 
LBR$C_TYP_USRHI (255) User library types — high 
end of range 
1 CRE$L_KEYLEN Maximum length of ASCII 
keys or, if 0, indicates 32-bit 
unsigned keys (binary keys) 
2 CRE$L_ALLOC Initial library file allocation 
3 CRE$L_IDXMAX Number of library indexes 
(maximum of eight) 
4 CRE$L_UHDMAX Number of additional bytes 
to reserve in module header 
5 CRE$L_ENTALL Number of index entries to 
preallocate 
6 CRE$L_LUHMAX Maximum number of library 
update history records to 
maintain 
7 CRE$L_VERTYP Format of library to create: 
CRE$C_VMSV2 VMS Version 2.0 
CRE$C_VMSV3 VMS Version 3.0 
8 CRE$L_IDXOPT Index key casing option: 
CRE$C_HLPCASING Treat character case as it is 
for help libraries 
CRE$C_OBJ CASING Treat character case as it is 
for object libraries 
CRE$C_MACTXTCAS Treat character case as it is 
for macro and text libraries 
9-19 Reserved by HP 


The input of uppercase and lowercase characters is treated differently for help, 
object, macro, and text libraries. For details, see the HP OpeVMS Command 
Definition, Librarian, and Message Utilities Manual. 
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Description 


dns 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Default file specification. The dns argument is the address of the string 
descriptor that points to the default file specification. See the OpenVMS Record 
Managenent Services Reference Manual for details about how defaults are 
processed. 


rlfna 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Related file name. The rlfna argument is the address of an RMS NAM block 
pointing to the related file name. You must specify rlfna for related file name 
processing to occur. If a related file name is specified, only the file name, 

type, and version fields of the NAM block are used for related name block 
processing. The device and directory fields are not used. See the OoeVMS 
Record Managenent Services Reference Manual for details on processing related 
file names. 


rns 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Resultant file specification returned. The rns argument is the address of a string 
descriptor pointing to a buffer that is to receive the resultant file specification 
string. If an error occurs during an attempt to open the library, the expanded 
name string is returned instead. 


rnslen 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 


Length of the resultant or expanded file name. The rnslen argument is the 
address of a longword receiving the length of the resultant file specification string 
(or the length of the expanded name string if there was an error in opening the 
library). 


You can call this routine only after you call LBR$INI_ CONTROL and before you 
call any other LBR routine except LBR$OUTPUT_HELP. 


When the library is successfully opened, the LBR routine reads the library header 
into memory and sets the default index to 1. 


If the library cannot be opened because it is already open for a write operation, 
LBR$OPEN retries the open operation every second for a maximum of 30 seconds 
before returning the RMS error, RMS$ FLK, to the caller. 
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LBR$ ERRCLOSE 


LBR$ ILLCREOPT 


LBR$ ILLCTL 
LBR$ ILLFMT 
LBR$ ILLFUNC 
LBR$ LIBOPN 
LBR$ NOFILNAM 


LBR$ OLDLIBRARY 


LBR$ OLDMISMCH 


LBR$ TYPMISMCH 
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Error. When the library was last modified while 
opened for write access, the write operation 
was interrupted. This left the library in an 
inconsistent state. 


Requested create options not valid or not 
supplied. 

Specified library control index not valid. 
Specified library format not valid. 

Specified library function not valid. 

Specified library already open. 

Error. The fns argument was not supplied or the 
RMS NAM block was not filled in. 


Success. The specified library has been opened; 
the library was created with an old library 
format. 

Requested library function conflicts with old 
library type specified. 

Library type does not match the requested type. 
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LBRSOUTPUT_HELP—Output Help Messages 


Format 


Returns 


Arguments 


The LBR$OUTPUT_HELP routine outputs help text to a user-supplied output 
routine. The text is obtained from an explicitly named help library or, optionally, 
from user-specified default help libraries. An optional prompting mode is 
available that enables LBR$QOUTPUT_HELP to interact with you and continue to 
provide help information after the initial help request has been satisfied. 


LBR$OUTPUT_HELP  output_routine [,output_width] [,line_desc] [,liprary_name] 
[ flags] [,input_routine] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


output_routine 
OpenVMS usage: procedure 


type: procedure value 
access: write only 
mechanism: by reference 


Name of a routine that writes help text a line at a time. The output_routine 
argument is the address of the procedure value of the routine to call. You should 
specify either the address of LIB$PUT OUTPUT or a routine of your own that 
has the same calling format as LIB$PUT OUTPUT. 


output_width 
OpenVMS usage: longword_signed 


type: longword (signed) 
access: read only 
mechanism: by reference 


Width of the help-text line to be passed to the user-supplied output routine. The 
output_width argument is the address of a longword containing the width of the 
text line to be passed to the user-supplied output routine. If you omit output_ 
width or specify it as 0, the default output width is 80 characters per line. 


line_desc 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Contents of the help request line) The line_desc argument is the address of 
a string descriptor pointing to a character string containing one or more help 
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keys defining the help requested, for example, the HELP command line minus 
the HELP command and HELP command qualifiers. The default is a string 
descriptor for an empty string. 


library_name 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Name of the main library. The library_name argument is the address of a string 
descriptor pointing to the main library file specification string. The default is a 
null string, which means you should use the default help libraries. If you omit 
the device and directory specifications, the default is SYS$HELP. The default file 
typeis .HLB. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags specifying help output options. Each programming language provides an 
appropriate mechanism for accessing these flags. The flags argument is the 
address of an unsigned longword that contains the following flags, when set: 


Flag Description 

HLP$M_PROMPT Interactive help prompting is in effect. 

HLP$M_PROCESS The process logical name table is searched for default help 
libraries. 

HLP$M_GROUP The group logical name table is searched for group default 


help libraries. 

HLP$M_SYSTEM The system logical name table is searched for system 
default help libraries. 

HLP$M_LIBLIST The list of default libraries available is output with the 
list of topics available. 

HLP$M_HELP The list of topics available in a help library is preceded by 
the major portion of the text on help. 


If you omit this longword, the default is for prompting and all default library 
searching to be enabled, but no library list is generated and no help text precedes 
the list of topics. 


input_routine 
OpenVMS usage: procedure 


type: procedure value 
access: read only 
mechanism: by reference 


Routine used for prompting. The input_routine argument is the address of the 
procedure value of the prompting routine. You should specify either the address 
of LIB$GET_INPUT or a routine of your own that has the same calling format as 
LIB$GET_INPUT. This argument must be supplied when the HELP command is 
run in prompting mode (that is, HLP$M_PROMPT is set or defaulted). 
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Description 


The LBR$OUTPUT_HELP routine provides a simple, one-call method to 
initiate an interactive help session. Help library bookkeeping functions, 
such as LBR$INI_CONTROL and LBR$OPEN, are handled internally. You 
should not call LBR$INI_ CONTROL or LBR$OPEN before you issue a call to 
LBR$OUTPUT_HELP. 


LBR$OUTPUT HELP accepts help keys in the same format as LBR$GET_HELP, 
with the following qualifications: 


e |f the keyword HELP is supplied, help text on HELP is output, followed by a 
list of HELP subtopics available. 


If no help keys are provided or if the line_desc argument is 0, a list of topics 
available in the root library is output. 


e |f the line_desc argument contains a list of help keys, then each key must be 
separated from its predecessor by a slash (/) or by one or more spaces. 


e The first key can specify a library to replace the main library as the root 
library (the first library searched) in which LBR$QOUTPUT_HELP searches 
for help. A key used for this purpose must have the form <@filespec>, where 
filespec is subject to the same restrictions as the library_name argument. If 
the specified library is an enabled user-defined default library, then filespec 
can be abbreviated as any unique substring of that default library’s logical 
name translation. 


In default library searches, you can define one or more default libraries for 
LBR$OUTPUT_HELP to search for help information not contained in the root 
library. Do this by equating logical names (HLP$LIBRARY, HLP$LIBRARY_ 

1, ... ,HLP$LIBRARY_999) to the file specifications of the default help libraries. 
You can define these logical names in the process, group, or system logical name 
table. 


If default library searching is enabled by the flags argument, LBR$OUTPUT _ 
HELP uses those flags to determine which logical name tables are enabled and 
then automatically searches any user default libraries that have been defined 

in those logical name tables. The library search order proceeds as follows: 

root library, main library (if specified and different from the root library), 
process libraries (if enabled), group libraries (if enabled), system libraries (if 
enabled). If the requested help information is not found in any of these libraries, 
LBR$OUTPUT_HELP returns to the root library and issues a “help not found” 
message. 


To enter an interactive help session (after your initial request for help has been 
satisfied), you must set the HLP$M_ PROMPT bit in the flags argument. 


You can encounter four different types of prompt in an interactive help session. 
Each type represents a different level in the hierarchy of help available to you. 


1. If the root library is the main library and you are not currently examining 
HELP for a particular topic, the prompt Topic? is output. 


2. If the root library is a library other than the main library and if you are 
not currently examining HELP for a particular topic, a prompt of the form 
@<ibrary-spec>Topic? is output. 


3. If you are currently examining HELP for a particular topic (and subtopics), a 
prompt of the form <keyword...>subtopic? is output. 
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4. A combination of 2 and 3. 


When you encounter one of these prompt messages, you can respond in any one 
of several ways. Each type of response and its effect on LBR$OUTPUT_HELP in 
each prompting situation is described in the following table: 


Response Action in the Current Prompt Environment’ 


keyword[... ] (1,2) Search all enabled libraries for these keys. 
(3,4) Search additional help for the current topic 
(and subtopic) for these keys. 

@filespec [keyword[ ... ]] (1,2) Same as above, except that the root library 
is the library specified by filespec. If the specified 
library does not exist, treat @filespec as a normal 
Key. 

(3,4) Same as above; treat Gfilespec as a normal 
key. 

? (1,2) Display a list of topics available in the root 
library. 

(3,4) Display a list of subtopics of the current 
topic (and subtopics) for which help exists. 

Carriage Return (1) Exit from LBR$OUTPUT_HELP. 

(2) Change root library to main library. 

(3,4) Strip the last keyword from a list of 
keys defining the current topic (and subtopic) 
environment. 

Ctrl/Z (1,2,3,4) Exit from LBR$OUTPUT_HELP. 


1K eyed to the prompt in the preceding list. 


Condition Values Returned 


LBR$ ILLINROU Input routine improperly specified or omitted. 
LBR$ ILLOUTROU Output routine improperly specified or omitted. 
LBR$ NOHLPLIS Error. No default help libraries can be opened. 
LBR$ TOOMNYARG Error. Too many arguments were specified. 
LBR$ USRINPERR Error. An error status was returned by the 


user-supplied input routine. 
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LBR$PUT_END—Write an End-of-Module Record 


Format 


Returns 


Argument 


Description 


The LBR$PUT_END routine marks the end of a sequence of records written toa 
library by the LBR$PUT_ RECORD routine. 


LBR$PUT_END _ library_index 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of a longword containing the index. 


Call LBR$PUT_END after you write data records to the library with the 
LBR$PUT_ RECORD routine. LBR$PUT END terminates a module by attaching 
a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the data. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$PUT_HISTORY—Write an Update History Record 


Format 


Returns 


Arguments 


Description 


The LBR$PUT_HISTORY routine adds an update history record to the end of the 
update history list. 


LBR$PUT_HISTORY  library_index ,record_desc 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


record_desc 
OpenVMS usage: char_string 


type: character string 
access: read only 
mechanism: by descriptor 


Library history record. The record_desc argument is the address of a string 
descriptor pointing to the record to be added to the library update history. 


LBR$PUT_HISTORY writes a new update history record. If the library already 
contains the maximum number of history records (as specified at creation time 
by CRE$L_LUHMAX; see LBR$OPEN for details), the oldest history record is 
deleted before the new record is added. 
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Condition Values Returned 


LBR$ NORMAL 
LBR$ INTRNLERR 
LBR$ NOHISTORY 


LBR$ RECLNG 
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Normal exit from the routine. 

Internal Librarian error. 

No update history. This is an informational code, 
not an error code. 

Record length greater than that specified by 
LBR$C_MAXRECSIZ. The record was not 
inserted or truncated. 
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LBR$PUT_MODULE—Puts a module and module’s RFA from 


Format 


Arguments 


memory space into current library (164 only) 


The LBR$PUT_MODULE routine puts an entire module, with the module's record 
file address (RFA), from memory space into the current library. 


LBR$PUT_MODULE _library_index, mod_addr, mod_len, txtrfa 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL library routine. The 
library_index argument is the address of the longword that contains the index. 


mod_addr 

OpenVMS usage: address 

type: quadword address 

access: read only 

mechanism: by 32-bit or 64-bit reference 


The address from which the Library service obtains the 64-bit address of where 
the module is mapped in memory. The mod_addr argument is the 32- or 64-bit 
virtual address of a naturally aligned quadword containing the virtual address 
location of the module to write to the library. 


mod_len 

OpenVMS usage: byte count 

type: quadword (unsigned) 
access: read only 

mechanism: by 32- or 64-bit reference 


The 64-bit virtual address of a naturally aligned quadword containing the length 
of the module that the Library service is to write into the library. 


txtrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


The module's record file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array receiving the RFA of the newly 
created module header. 
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Description 


The LBR$PUT_MODULE routine puts an entire module, with the module's record 
file address (RFA), from memory space into the current library. LBR$PUT_ END 
is not required when you write an entire module to the current library. 
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LBR$PUT_RECORD—Write a Data Record 


Format 


Returns 


Arguments 


The LBR$PUT_ RECORD routine writes a data record beginning at the next free 
location in the library. 


LBR$PUT_RECORD library_index ,bufdes ,txtrfa [, mod_size] 


OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


bufdes 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Record to be written to the library. The bufdes argument is the address of 

a string descriptor pointing to the buffer containing the output record. The 
maximum record size for VAX libraries is symbolically defined as LBR$C_ 
MAXRECSIZ; for 164 and Alpha libraries, the symbolic maximum record size is 
ELBR$ MAXRECSIZ. 


txtrfa 

OpenVMS usage: vector _longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


Record’s file address (RFA) of the module header. The txtrfa argument is the 
address of a 2-longword array receiving the RFA of the newly created module 
header upon the first call to LBR$PUT_RECORD. 


mod_size 

OpenVMS usage: byte count 

type: longword (unsigned) 
access: read only 
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mechanism: by value 


The value from mod_size is read on the first call to this routine and ignored 
otherwise. The value specifies the size of the module to be entered so that 
contiguous space is allocated within the library for that module. This argument 
is ignored for non-ELF object libraries and for data-reduced ELF object libraries. 
The LBR$PUT_END routine is still required to terminate the byte stream and 
close off the module. 


Description 


If this is the first call to LBR$PUT_RECORD, this routine first writes a module 
header and returns its RFA to the 2-longword array pointed to by txtrfa. 
LBR$PUT_ RECORD then writes the supplied data record to the library. On 
subsequent calls to LBR$PUT RECORD, this routine writes the data record 
beginning at the next free location in the library (after the previous record). The 
last record written for the module should be followed by a call toLBR$PUT_END. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$REPLACE_KEY—Replace a Library Key 


Format 


Returns 


Arguments 


The LBR$REPLACE KEY routine modifies or inserts a key into the library. 


LBR$REPLACE_KEY library_index ,key_name ,oldrfa ,newrfa [, flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


key_name 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


For libraries with ASCII keys, the key_name argument is the address of a string 
descriptor for the key. 


For libraries with binary keys, the key_name argument is the address of an 
unsigned longword value for the key. 
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oldrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Old record file address (RFA). The oldrfa argument is the address of a 2- 
longword array containing the original RFA (returned by LBR$LOOKUP_KEY) of 
the module header associated with the key you are replacing. 


newrfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


New RFA. The newrfa argument is the address of a 2-longword array containing 
the RFA (returned by LBR$PUT_ RECORD) of the module header associated with 


the new key. 

flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


If present, the flags argument specifies the type of key being replaced. The flag 
bits are as follows: 


Flag Bits Description 
LBR$SYM_WEAK =O0x1 UNI X-style weak symbol attribute 
LBR$SYM_GROUP =0x2 Group symbol attribute 


If this argument is not present, NonGroup-Global is the assumed type. In this 
case, all type lists are searched and the entries removed. The new symbol is 
placed in the new NonGroup-Global definition with newrfa as the defining 
module. 


If this parameter is present, it represents the flags set for the type of symbol 
being replaced. The replacement is done in place without losing its position in 
the type list. If the symbol does not exist when the call to this routine is made, 
the new definition is placed at the end of the type list for the specified type. 


Because there are now different symbol definition types, HP advises using the 
LBR$DELETE_KEY routine followed by the LBR$INSERT_KEY routine when 
the old key and new key differ in definition type. 


Description 


If LBR$REPLACE_KEY does not find the key in the current index, it calls the 
LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does find 
the key, it modifies the key entry in the index so that it points to the new module 
header. 
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Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ INVRFA Specified RFA not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$RET_RMSSTV—Return OpenVMS RMS Status Value 


The LBR$RET_RMSSTV routine returns the status value of the last OpenVMS 
RMS function performed by any LBR subroutine. 


Format 
LBR$RET_RMSSTV 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
None. 
Description 


The LBR$RET_RMSSTV routine returns, as the status value, the status of the 
last RMS operation performed by the Librarian. Each programming language 
provides an appropriate mechanism for accessing RMS status values. 


Condition Values Returned 


This routine returns any condition values returned by RMS routines. 
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LBR$SEARCH—Search an Index 


Format 


Returns 


Arguments 


The LBR$SEARCH routine finds index keys that point to specified data. 


LBR$SEARCH _library_index ,index_number ,rfa_to_find ,routine_name [, flags] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


index_number 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library index number. The index_number argument is the address of a 
longword containing the number of the index you want to search. 


rfa_to_find 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: write only 

mechanism: by reference 


Record file address (RFA) of the module whose keys you are searching for. The 
rfa_to find argument is the address of a 2-longword array containing the RFA 
(returned earlier by LBR$LOOKUP_KEY or LBR$PUT_ RECORD) of the module 
header. 
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routine_name 
OpenVMS usage: procedure 


type: procedure value 
access: read only 
mechanism: by reference 


Name of a user-supplied routine to process the keys. The routine_name 
argument is the address of the procedure value of a user-supplied routine to call 
for each key entry containing the RFA (in other words, for each key that points to 
the same module header). 


This user-supplied routine cannot contain any calls to LBR$DELETE_KEY or 
LBR$INSERT_KEY. 


flags 

OpenVMS usage: mask_longword 
type: longword unsigned 
access: read only 
mechanism: by reference 


If present and nonzero, the flags argument specifies the type, or all types, of the 
key provided. The flag bits are as follows: 


Flag Bits Description 

LBR$M_SYM_WEAK =Oxl UNIX-style weak symbol attribute 
LBR$M_SYM_GROUP =0x2 Group symbol attribute 
LBR$M_SYM_ALL =0x80000000 All symbols 


The user routine is provided the symbol’s type through an additional third 
parameter. 


Description 


The LBR$SEARCH routine searches the library index for symbols with the given 
RFA and calls the supplied routine with those symbols. 


Use LBR$SEARCH to find index keys that point to the same module header. 
Generally, in index number 1 (the module name table), just one key points to 
any particular module; thus, you would probably use this routine only to search 
library indexes where more than one key points to a module. For example, you 
might call LBR$SEARCH to find all the symbols in the symbol index that are 
associated with an object module in an object library. 


If LBR$SEARCH finds an index key associated with the specified RFA, it calls a 
user-supplied routine with two arguments: 


e The key argument, which is the address of either of the following items: 
- A string descriptor for the key name (libraries with ASCII key names) 
- An-unsigned longword for the key value (libraries with binary keys) 


e TheRFA argument, which is the address of a 2-longword array containing the 
RFA of the module header 
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e« The key’s type, whose flag bits are as follows: 


Flag Bits 


Description 


LBR$M_SYM_WEAK =1 
LBR$M_SYM_GROUP =2 


UNIX-style weak symbol attribute 
Group symbol attribute 


The user routine must return a value to indicate success or failure. If the 
specified user routine returns a false value (low bit =0), then the index search 


terminates. 


Note that the key found by LBR$SEARCH is valid only during the call to the 
user-supplied routine. If you want to use the key later, you must copy it. 


Condition Values Returned 


LBR$ ILLCTL 
LBR$ ILLIDXNUM 
LBR$ KEYNOTFND 


LBR$ LIBNOTOPN 


Specified library control index not valid. 
Specified library index number not valid. 


Library routine did not find any keys with the 
specified RFA. 


Specified library not open. 
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LBR$SET_INDEX—Set the Current Index Number 


Format 


Returns 


Arguments 


Description 


The LBR$SET_INDEX routine sets the index number to use when processing 
libraries that have more than one index. 


LBR$SET_INDEX _library_index ,index_number 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


index_number 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Index number you want to establish as the current index number. The index_ 
number argument is the address of the longword that contains the number of 
the index you want to establish as the current index. Refer to Section 13.1.2.3. 


When you call LBR$INI_CONTROL, the Librarian sets the current library index 
to 1 (the module name table, unless the library is a user-developed library). If 
you need to process another library index, you must use LBR$SET_INDEX to 
change the current library index. 


Note that macro, help, and text libraries contain only one index; therefore, you 
do not need to call LBR$SET_INDEX. Object libraries contain two indexes. If 
you want to access the global symbol table, you must call the LBR$SET_INDEX 
routine to set the index number. User-developed libraries can contain more than 
one index; therefore, you may need to call LBR$SET_INDEX to set the index 
number. 


Upon successful completion, LBR$SET_INDEX sets the current library index to 
the requested index number. LBR routines number indexes starting with 1. 
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Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ ILLIDXNUM Library index number specified not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$SET_LOCATE—Set Record Access to Locate Mode 


Format 


Returns 


Argument 


Description 


The LBR$SET_LOCATE routine sets the record access of LBR subroutines to 
locate mode. 


LBR$SET_LOCATE _library_index 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


Librarian record access may be set to move mode (the default set by LBR$SET_ 
MOVE) or locate mode. The setting affects the operation of the LBR$GET_ 
RECORD routine. 


If move mode is set (the default), LBR$GET RECORD copies the requested 
record to the specified user buffer. If locate mode is set, the record is not copied. 
Instead, the outbufdes descriptor is set to reference the internal LBR subroutine 
buffer that contains the record. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBR$SET_MODULE—Read or Update a Module Header 


Format 


Returns 


Arguments 


The LBR$SET_ MODULE routine reads, and optionally updates, the module 
header associated with a given record's file address (RFA). 


LBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen] [,updatedesc] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


rfa 

OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Record’s file address (RFA) associated with the module header. The rfa argument 
is the address of a 2-longword array containing the RFA returned by LBR$PUT _ 
RECORD or LBR$LOOKUP_KEY. 


bufdesc 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Buffer that receives the module header. The bufdesc argument is the address 
of a string descriptor pointing to the buffer that receives the module header. 
The buffer must be the size specified by the symbol MHD$B_USRDAT plus the 
value of the CRE$L_UHDMAxX create option. The MHD$ and CRE$ symbols 
are defined in the modules $MHDDEF and $CREDEF, which are stored in 
SYS$LIBRARY:STARLET.MLB. 
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buflen 

OpenVMS usage: longword_signed 
type: longword (signed) 
access: write only 
mechanism: by reference 


Length of the module header. The buflen argument is the address of a longword 
receiving the length of the returned module header. 


updatedesc 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Additional information to be stored with the module header. The updatedesc 
argument is the address of a string descriptor pointing to additional data that 
the Librarian stores with the module header. If you include this argument, the 
Librarian updates the module header with the additional information. 


Description 


If you specify bufdesc, the LBR routine returns the module header into the 
buffer. If you specify buflen, the routine also returns the buffer’s length. If you 
specify updatedesc, the routine updates the header information. 


You define the maximum length of the update information (by specifying a value 
for CRE$L_UHDMAX) when you create the library. The Librarian zero-fills the 
information if it is less than the maximum length or truncates it if it exceeds the 
maximum length. 


Condition Values Returned 


LBR$ HDRTRUNC Buffer supplied to hold the module header was 
too small. 

LBR$ ILLCTL Specified library control index not valid. 

LBR$ ILLOP Error. The updatedesc argument was supplied 


and the library was a Version 1.0 library or the 
library was opened only for read access. 


LBR$ INVRFA Specified RFA does not point to a valid module 
header. 
LBR$ LIBNOTOPN Specified library not open. 


LBR-86 Librarian (LBR) Routines 


Librarian (LBR) Routines 
LBR$SET_MOVE 


LBR$SET_MOVE—Set Record Access to Move Mode 


Format 


Returns 


Argument 


Description 


The LBR$SET_MOVE routine sets the record access of LBR subroutines to move 
mode. 


LBR$SET_MOVE _library_index 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


library_index 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Library control index returned by the LBR$INI_ CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 


Librarian record access may be set to move mode (the default, set by LBR$SET_ 
MOVE) or locate mode. The setting affects the operation of the LBR$GET _ 
RECORD routine. If move mode is set, LBR$GET RECORD copies the requested 
record to the specified user buffer. For details, see the description of LBR$GET_ 
RECORD. 


Condition Values Returned 


LBR$ ILLCTL Specified library control index not valid. 
LBR$ LIBNOTOPN Specified library not open. 
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LBRS$UNMAP_MODULE—Unmaps a module from process P2 space 


(164 only) 
The LBR$UNMAP_MODULE routine unmaps a module from process P2 space. 
Format 
LBR$PUT_MODULE _library_index, txtrfa 
Arguments 
library_index 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Library control index returned by the LBR$INI_CONTROL library routine. The 
library_index argument is the address of the longword that contains the index. 
txtrfa 
OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
The module’s record file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array that specifies the RFA of the 
module header. 
Description 


The LBR$UNMAP_ MODULE routine unmaps the module, with the record file 
address in txtrfa, from process P2 space. This action releases the resources used 
to map the module. 


Unlike other LBR services that use RMS services, LBR$UNMAP_ MODULE also 
uses system services. Because of this, the secondary status for error returns is 
placed in LBR$GL_SUBSTS. Use this to find further status when an error is 
returned. 
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Lightweight Directory Access Protocol (LDAP) 
Routines 


14.1 Introduction 


This chapter describes the C language application programming interface (API!) to 
the Lightweight Directory Access Protocol (.DAP). This API supports Version 3 of 
the LDAP API (LDAP v3), and includes support for controls, information hiding, 
and thread safety. The LDAP API is available on OpenVMS Alpha only. 


The C LDAP API is designed to be powerful, yet simple to use. It defines 
compatible synchronous and asynchronous interfaces to LDAP to support a 
wide variety of applications. This chapter gives a brief overview of the LDAP 
model, and describes how the application program uses the API to obtain LDAP 
information. The API calls are described in detail, followed by a section that 
provides some example code demonstrating the use of the API. 


14.1.1 Overview of the LDAP Model 


LDAP is the lightweight directory access protocol, which is based on a client- 
server model. In this model, a client makes a TCP connection to an LDAP server, 
over which it sends requests and receives responses. 


The LDAP information model is based on the entry, which contains information 
about some object (for example, a person). Entries are composed of attributes, 
which have a type and one or more values. Each attribute has a syntax that 
determines what kinds of values are allowed in the attribute (for example, ASCI| 
characters or a jpeg photograph) and how those values behave during directory 
operations (for example, whether case is significant during comparisons). 


Entries may be organized in a tree structure, usually based on political, 
geographical, or organizational boundaries. Each entry is uniquely named 
relative to its sibling entries by its relative distinguished name (RDN) consisting 
of one or more distinguished attribute values from the entry. At most, one value 
from each attribute may be used in the RDN. For example, the entry for the 
person Babs J ensen might be named with the Barbara J ensen value from the 
commonName attribute. 


A globally unique name for an entry, called a distinguished name or DN, is 
constructed by concatenating the sequence of RDNs from the entry up to the root 
of the tree. For example, if Babs worked for the University of Michigan, the DN 
of her U-M entry might be the following: 


cn=Barbara Jensen, o=University of Michigan, c=US 


Operations are provided to authenticate, search for and retrieve information, 
modify information, and add and delete entries from the tree. The next sections 
give an overview of how the API is used and provide detailed descriptions of the 
LDAP API calls that implement all of these functions. 
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14.1.2 Overview of LDAP API Use 
An application generally uses the C LDAP API in four simple steps. 


e Initialize an LDAP session with a primary LDAP server. The ldap init () 
function returns a handle to the session, allowing multiple connections to be 
open at once. 


e Authenticate to the LDAP server. The ldap _bind() function supports a 
variety of authentication methods. 


¢ Perform some LDAP operations and obtain some results. The ldap_search( ) 
function returns results that can be parsed by ldap parse result(), 
ldap first _entry(), and ldap next entry(). 


e Close the session. The ldap_unbind() function closes the connection. 


Operations can be performed either synchronously or asynchronously. The names 
of the synchronous functions end in _s. For example, a synchronous search can be 
completed by calling ldap search _s(). An asynchronous search can be initiated 
by calling ldap_search(). All synchronous functions return an indication of the 
outcome of the operation (for example, the constant LDAP_SUCCESS or some 
other error code). The asynchronous functions make available to the caller the 
message id of the operation initiated. This id can be used in subsequent calls 

to ldap_result() to obtain the result(s) of the operation. An asynchronous 
operation can be abandoned by calling ldap _abandon() or ldap abandon ext (). 


Results and errors are returned in an opaque structure called LDAPMessage. 
Functions are provided to parse this structure, step through entries and 
attributes returned. Functions are also provided to interpret errors. Later 
sections of this chapter describe these functions in more detail. 


LDAPv3 servers may return referrals to other servers. By default, 
implementations of this API will attempt to follow referrals automatically for the 
application. This behavior can be disabled globally (using the ldap_set_option() 
call) or on a per-request basis through the use of a server control. 


As in the LDAPv3 protocol, all DNs and string values that are passed into or 
produced by the C LDAP API are represented as UTF-8 characters. Conversion 
functions are described in Section 14.20. 


For compatibility with existing applications, implementations of this API will, 
by default, use Version 2 of the LDAP protocol. Applications that intend to take 
advantage of LDAP v3 features will need to use the ldap _set_option() call with 
a LDAP_OPT_PROTOCOL_VERSION switch set to Version 3. 


The file LDAP_EXAMPLE.C in SYS$EXAMPLES contains an example program 
that demonstrates how to use the LDAP API on OpenVMS. 


14.1.3 LDAP API Use on OpenVMS Systems 


This release of the LDAP API provides support for client applications written in 
Cor CH. 


In order to use the LDAP API, a program must use an include statement of the 
form: 


#include <ldap.h> 


The LDAP.H header file includes prototypes and data structures for all of the 
functions that are available in the LDAP API. 
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The shareable image LDAP$SHR.E XE includes run-time support for LDAP 
applications. This shareable image resides in SYS$LIBRARY and should be 
included in the library |MAGELIB.OLB, which means that no special action is 
necessary to link or run your programs. For example: 


$ type myprog.c 


/* A not very useful program */ 
#include <stdio.h> 

#include <ldap.h> 

void main(int argc, char *argv[]) 


LDAP *1d; 
if (argc != 2) { 

printf ("usage: %s <hostname>\n",argv[0]); 
return; 
ld = ldap init (argv[1],LDAP PORT) ; 
if (1d != NULL) { 

printf ("ldap init returned 0x%p\n",1d) ; 
} else { 

printf ("ldap init failed\n") ; 


cc myprog 

link myprog 

myprog :== $mydisk: [mydir]myprog.exe 
$ myprog fred 

ldap_init returned 0xA6748 


TH 2 ee 


14.1.4 64-bit Addressing Support 
This section describes the LDAP 64-bit addressing support. 


14.1.4.1| Background 
OpenVMS Alpha provides support for 64-bit virtual memory addressing. 
Applications that are built using a suitable compiler may take advantage of 
the 64-bit virtual address space to map and access large amounts of data. 


The OpenVMS LDAP API supports both 32- and 64-bit client applications. In 
order to allow this, separate entry points are provided in the library for those 
functions that are sensitive to pointer size. 


When a user module is compiled, the header file LDAP.H determines the pointer 
size in effect and uses the C preprocessor to map the function names into 

the appropriate library entry point. This mapping is transparent to the user 
application and is effected by setting the /POINTER_SIZE qualifier at compilation 
time. 


For LDAP API users, switching between different pointer sizes should need only 
a recompilation—no code changes are necessary. 


This means that programs using the specification for the C LDAP API, as 
described in the Internet Engineering Task Force (IETF) documentation, can 

be built on OpenVMS with either 32-bit or 64-bit pointer size, without having to 
change the source code. 
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14.1.4.2 Implementation 


The OpenVMS LDAP library uses 64-bit pointers internally and is capable of 
dealing with data structures allocated by the caller from 64-bit address space. 


Applications that use 32-bit pointers will use the 32-bit function entry points 

in the library. This means they can pass arguments that are based on 32-bit 
pointers and can assume that any pointers returned by the library will be 32-bit 
safe. 


While the mapping performed by LDAP.H is designed to be transparent, there 
may be occasions where it is useful (for example in debugging) to understand the 
consequences of having both 32- and 64-bit support in the same library. 


14.1.4.2.1 Library Symbol Names The symbols exported by the LDAP$SHR 
OpenVMS run-time library differ from those specified in the IETF C LDAP API 
specification. 


The header file LDAP.H maps user references to LDAP API function names to 
the appropriate LDAP$SHR symbol name. Therefore, any application wishing to 
use the OpenVMS LDAP API must include the version of LDAP.H that ships with 
OpenVMS. 


All of the functions in the OpenVMS LDAP library are prefixed with the facility 
code "LDAP$". 


For those functions where the caller’s pointer size is significant, the name of the 
64-bit entry point will have a " 64" suffix, while the name of the 32-bit jacket 
will have a "_32" suffix. Functions that are not sensitive to pointer size have no 
special suffix. 


For example, the function ldap modify() is sensitive to the caller's pointer size 
(because one of its arguments is an array of pointers). Therefore, the library 
exports symbols for LDAP$LDAP_MODIFY_64 and LDAP$LDAP_MODIFY_ 
32. For the function ldap simple bind(), which is not sensitive to the caller's 
pointer size, a single entry point, LDAP$LDAP_SIMPLE_BIND, exists in the 
library. 


Because OpenVMS imposes a 31-character limit on the length of symbol 
names, certain functions in the library have names which are abbreviated 
versions of the public API name. For example, in the case of the function 

ldap parse sasl bind result(), the library provides two entry points, namely 
LDAP$LDAP_PRS SASL_BIND_RES 32 and LDAP$LDAP_PRS SASL BIND_ 
RES 64. 


14.1.4.2.2 LDAP Data Structures The LDAP API defines various data 
structures which are used to pass information to and from a client application. 
Some of these structures are opaque; that is, their internal layout is not visible 
to a dient application. In such cases, the API may return a pointer to such 

a structure, but the only use of such a pointer to a client application is as a 
parameter to subsequent library calls. 


Some structures are public. Their contents are defined by the API, and client 
applications may allocate and manipulate such structures or use them as 
parameters to LDAP functions. 


All data structures used by the API are defined with "natural" alignment; that 
is, each member of a data structure will be aligned on an address boundary 
appropriate to its type. 
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Opaque Data Structures 
The following data structures are opaque. Applications should not make any 
assumptions about the contents or size of such data structures. 


typedef struct ldap 
LDAP; 


typedef struct ldapmsg 
LDAPMessage; 


typedef struct berelement 
BerElement ; 


Public Data Structures 


The following data structures are described in the IETF documents relating to 
the LDAP API, and definitions are provided for them in LDAP.H. Applications 
may allocate and manipulate such structures, as well as use them in calls to the 
LDAP API. 


truct berval { .. } 
erValue; 


typedef 


Wn 


typedef struct ldapapiinfo { .. } 
LDAPAPIInfo; 

typedef struct ldap apifeature info { .. } 
LDAPAPIFeaturelInfo; 


typedef struct ldapcontrol { .. } 
LDAPControl; 


typedef struct ldapmod { .. } 
LDAPMod; 


Note that the pointer size in effect at compilation time determines the layout of 
data structures, which themselves contain pointer fields. Since all of the public 
data structures listed here contain one or more pointers, their size and layout will 
differ depending on the pointer size. 


For example, in the case of the structure berval, the API provides the following 
definition: 


struct berval { 


ber len t bv_len; 
char *bv_val; 
} BerValue; 


(where ber_len_t is equivalent on OpenVMS to an unsigned 32-bit integer). For a 
module compiled using 32-bit pointer size, the layout of a BerValue at address A 
would look like this: 


bv_len A 
bv_val :A+4 
VM-0729A-Al 


In the case of a 64-bit compilation, the layout would be: 
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rad 


unused *** [A 


: A+8 


VM-0730A-Al 


The following code would therefore work correctly regardless of pointer size: 


#include <ldap.h> 


"char *buff; 
BerValue val; 


, buff = (char *)malloc(255); 


255} 
buff; 


val.bv_len 
val.bv_val 


14.1.4.3 Mixing Pointer Sizes 


Two modules that include LDAP.H can be compiled with different pointer sizes 
and linked together. While each module may use the LDAP API on its own, it 
may not be possible for both modules to share LDAP-related data. 


None of the public LDAP data structures is directly compatible between 32- and 
64-bit modules. For example, a BerValue that has been allocated by a 32-bit 
module does not have the same layout as a BerValue which a 64-bit module 
expects to see, and consequently cannot be exchanged between two such modules 
without some sort of data conversion taking place. 


Opaque data structures (such as LDAP *) have only a single structure definition 
inside the library, and so pointers to such structures may be exchanged between 
32- and 64-bit callers. Note that these structures are allocated only by the library 
itself, and, in the case of a 64-bit caller, these structures may be allocated in 64- 
bit space. So while the LDAP handle returned to a 32-bit caller of ldap init () 
could safely be used by a 64-bit module, the reverse may not be true. 


14.1.5 Multithreading Support 


The OpenVMS LDAP API may be used by a multi-threaded application. Two of 
the functions in the library, ldap perror() and ldap result2error(), are not 
thread-safe. 
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14.2 Common Data Structures and Memory Handling 


The following are definitions of some data structures that are common to several 
LDAP API functions. 


typedef struct ldap LDAP; 

typedef struct berelement BerElement ; 
typedef struct ldapmsg LDAPMessage; 
typedef struct berval { 


ber len t bv_len; 
char *bv_val; 
} BerValue; 


struct timeval; 


The LDAP structure is an opaque data type that represents an LDAP session. 
Typically, this corresponds to a connection to a single server, but it may 
encompass several server connections in LDAPv3 referrals. 


The LDAPMessage structure is an opaque data type that is used to return 

entry, reference, result, and error information. An LDAPMessage structure may 
represent the beginning of a list or a chain of messages that contain a series of 
entries, references, and result messages that are returned by LDAP operations, 
such as search. LDAP API functions, such as ldap_parse_result(), that operate 
on message chains which may contain more than one result message, always 
operate on the first result message in the chain. See Section 14.17 for more 
information. 


The BerElement structure is an opaque data type that is used to hold data and 
state information about encoded data. 


The berval structure is used to represent arbitrary binary data, and its fields 
have the following meanings: 

bv_len Length of data in bytes. 

bv_val A pointer to the data itself. 

The timeval structure is used to represent an interval of time, and its fields have 
the following meanings: 

tv_sec Seconds component of time interval. 

tv_usec Microseconds component of time interval. 

All memory that is allocated by a function in this C LDAP API and returned to 
the caller should be disposed of by calling the appropriate free function provided 


by this API. The correct free function to call is documented in each section of this 
chapter where a function that allocates memory is described. 


Memory that is allocated outside of the C LDAP API must not be disposed of 
using a function provided by this API. 


The following is a complete list of free functions that are used to dispose of 
allocated memory: 
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ber_bvecfree () 


ber_bvfree() 


ber_ free () 


ldap_control free () 
ldap_controls free () 
ldap_memfree () 

ldap _msgfree () 
ldap_value_free() 


ldap_value_ free len() 


14.3 LDAP Error Codes 


Many of the LDAP API functions return LDAP error codes, some of which 
indicate local errors and some of which may be returned by servers. All of the 
LDAP error codes returned will be positive integers; those between 0x00 and 
0x50 are returned from the LDAP server, those above 0x50 are generated by the 
API itself. Supported error codes are as follows (hexadecimal values are given in 


parentheses after the constant): 


an 


BE) 


ion 


an 


be 


an 


an 


an 


an 


LDAP REFERRAL (0x0a 
LDAP _ADMINLIMIT EXCEEDED (0x0b) 
LDAP UNAVAILABLE CRITICAL EXTENSION (0x0c) -- new 


LDAP SUCCESS (0x00) 
LDAP OPERATIONS ERROR (0x01) 


DAP PROTOCOL ERROR (0x02) 
DAP TIMELIMIT EXCEEDED (0x03) 


LDAP _SIZELIMIT EXCEEDED (0x04) 
LDAP COMPARE FALSE (0x05) 
LDAP COMPARE TRUE (0x06) 


DAP STRONG AUTH NOT SUPPORTED (0x07) 


LDAP STRONG AUTH REQUIRED (0x08) 


DAP CONFIDENTIALITY REQUIRED (0x0d) 
DAP SASL BIND IN PROGRESS (0x0e) 


LDAP NO SUCH ATTRIBUTE (0x10) 
LDAP UNDEFINED TYPE (0x11) 


DAP INAPPROPRIATE MATCHING (0x12) 
DAP CONSTRAINT VIOLATION (0x13) 


LDAP TYPE OR VALUE EXISTS (0x14) 


LDAP INVALID SYNTAX (0x15) 
LDAP _NO SUCH OBJECT (0x20) 
LDAP ALIAS PROBLEM (0x21) 


DAP INVALID DN SYNTAX (0x22) 
DAP IS LEAF (0x23) 


LDAP ALIAS DEREF PROBLEM (0x24) 
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-- new 


-- new 


-- new 


-- new 


-- not used 


in LDAPv3 
in LDAPv3 
in LDAPv3 
in LDAPv3 
in LDAPv3 


in LDAPv3 
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LDAP_INAPPROPRIATE AUTH (0x30) 
LDAP_INVALID CREDENTIALS (0x31) 
LDAP_INSUFFICIENT ACCESS (0x32) 
LDAP_BUSY (0x33) 

LDAP_UNAVAILABLE (0x34) 
LDAP_UNWILLING TO PERFORM (0x35) 
LDAP_LOOP DETECT (0x36) 

LDAP NAMING VIOLATION (0x40) 
LDAP_OBJECT CLASS VIOLATION (0x41) 
LDAP NOT ALLOWED ON NONLEAF (0x42) 
LDAP_NOT ALLOWED ON_RDN (0x43) 
LDAP_ALREADY EXISTS (0x44) 


LDAP NO OBJECT CLASS MODS (0x45) 
LDAP RESULTS TOO LARGE (0x46) -- reserved for CLDA 


LDAP AFFECTS MULTIPLE DSAS (0x47) -- new in LDAPv3 
LDAP OTHER (0x50) 
LDAP SERVER DOWN (0x51) 


LDAP_LOCAL ERROR (0x52) 
LDAP_ENCODING ERROR (0x53) 

LDAP DECODING ERROR (0x54) 
LDAP_TIMEOUT (0x55) 

LDAP_AUTH UNKNOWN (0x56) 

LDAP FILTER ERROR (0x57) 
LDAP_USER_CANCELLED (0x58) 
LDAP_PARAM ERROR (0x59) 

LDAP_NO MEMORY (0x5a) 
LDAP_CONNECT_ERROR (0x5b) 

LDAP NOT SUPPORTED (0x5c) 
LDAP_CONTROL NOT FOUND (0x5d) 
LDAP NO RESULTS RETURNED (0x5e) 
LDAP MORE RESULTS TO RETURN (0x5f) 


LDAP CLIENT LOOP (0x60) 
LDAP REFERRAL LIMIT EXCEEDED (0x61) 


14.4 Initializing an LDAP Session 


The ldap_init() function initializes a session with an LDAP server. The server 
is not actually contacted until an operation is performed that requires it, allowing 
various options to be set after initialization 


LDAP *ldap_ init ( 


const char *hostname, 
int portno) ; 
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Use of the following function is deprecated. 


LDAP *ldap_open ( 
const char *hostname, 
int portno) ; 


Unlike ldap init(), the ldap open() function attempts to make a server 
connection before returning to the caller. A more complete description can be 
found in RFC 1823. 


Parameters are as follows: 


hostname Contains a space-separated list of hostnames or dotted strings 
representing the IP address of hosts running an LDAP server to 
connect to. Each hostname in the list can include an optional port 
number which is separated from the host itself with a colon (:) 
character. The hosts are tried in the order listed, stopping with the 
first one to which a successful connection is made. Note that only 
ldap open() attempts to make the connection before returning to the 
caller. ldap init () does not connect to the LDAP server. 


portno Contains the TCP port number to connect to. The default LDAP port of 
389 can be obtained by supplying the constant LDAP_PORT. If a host 
includes a port number, then this parameter is ignored. 


The ldap_init() and ldap _open() functions both return a session handle, 

a pointer to an opaque structure that should be passed to subsequent calls 
pertaining to the session. These functions return NULL if the session cannot be 
initialized, in which case the operating system error reporting mechanism can be 
checked to see why the call failed. 


Note that if you connect to an LDAP Version 2 server, one of the ldap_bind( ) 
calls must be completed before other operations can be performed on the session. 
LDAPv3 does not require that a bind operation be completed before other 
operations can be performed. 


The calling program can set various attributes of the session by calling the 
functions described in the next section. 


14.5 LDAP Session Handle Options 


The LDAP session handle returned by ldap init() is a pointer to an opaque 
data type representing an LDAP session. Formerly, this data type was a structure 
exposed to the caller, and various fields in the structure could be set to control 
aspects of the session, such as size and time limits on searches. 


To insulate callers from inevitable changes to this structure, these aspects of the 
session are now accessed through a pair of accessor functions. 


The ldap_get_option() function is used to access the current value of various 
session-wide parameters. The ldap set _option() function is used to set the 
value of these parameters. Note that some options are READ-ONLY and cannot 
be set; it is an error to call ldap _set_option() and attempt to set aREAD-ONLY 


option. 
int ldap_get_option ( 
LDAP *l1d, 
int option, 
void *outvalue 


LDAP-10 Lightweight Directory Access Protocol (LDAP) Routines 


Lightweight Directory Access Protocol (LDAP) Routines 
14.5 LDAP Session Handle Options 


int ldap_set_option ( 


LDAP *1d, 
int option, 
const void *invalue 


ie 


Parameters are as follows: 


Id 


option 


The session handle. If this is NULL, a set of global defaults is accessed. New 
LDAP session handles created with ldap _init() or ldap open() inherit 
their characteristics from these global defaults. 


The name of the option being accessed or set. This parameter should be one of 
the following constants, which have the indicated meanings. After the constant, 
the actual hexadecimal value of the constant is listed in parentheses. 


LDAP_OPT_DESC (0x01) 


LDAP_OPT_DEREF (0x02) 


LDAP_OPT_SIZELIMIT (0x03) 


LDAP_OPT_TIMELIMIT (0x04) 


LDAP_OPT_REFERRALS (0x08) 


Type for invalue parameter: not applicable 
(option is read-only). 
Type for outvalue parameter: int * 


Description: The underlying socket 
descriptor corresponding to the primary 
LDAP connection. This option is read-only 
and cannot be set. 


Type for invalue parameter: int * 
Type for outvalue parameter: int * 


Description: Determines how aliases 

are handled during search. It can have 
one of the following values: LDAP_ 
DEREF_NEVER (0x00), LDAP_DEREF _ 
SEARCHING (0x01), LDAP_DEREF _ 
FINDING (0x02), or LDAP_DEREF _ 
ALWAYS (0x03). The LDAP_DEREF _ 
SEARCHING value means aliases should 
be dereferenced during the search but 

not when locating the base object of the 
search.The LDAP_DEREF_FINDING value 
means aliases should be dereferenced when 
locating the base object but not during the 
search. 


Type for invalue parameter: int * 
Type for outvalue parameter: int * 


Description: A limit on the number of 
entries to return from a search. A value of 
LDAP_NO_LIMIT (0) means no limit. 


Type for invalue parameter: int * 
Type for outvalue parameter: int * 


Description: A limit on the number of 
seconds to spend on a search. A value of 
LDAP_NO_LIMIT (0) means no limit. 


Type for invalue parameter: int (LDAP_ 
OPT_ON or LDAP_OPT_OFF) 
Type for outvalue parameter: int * 


Description: Determines whether the 
LDAP library automatically follows 
referrals returned by LDAP servers. It 
can be set to one of the constants LDAP_ 
OPT_ON (1) or LDAP_OPT_OFF (0). 
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outvalue 


LDAP_OPT_RESTART (0x09) 


LDAP_OPT_PROTOCOL_ 
VERSION (0x11) 


LDAP_OPT_SERVER_ 
CONTROLS (0x12) 


LDAP_OPT_CLIENT_ 
CONTROLS (0x13) 


LDAP_OPT_HOST_NAME 


(0x30) 


LDAP_OPT_ ERROR_NUMBER 
(0x31) 


LDAP_OPT_ERROR_STRING 
(0x32) 


Type for invalue parameter: int (LDAP_ 
OPT_ON or LDAP_OPT_OFF) 
Type for outvalue parameter: int * 


Description: Determines whether LDAP 
1/O operations should automatically be 
restarted if they abort prematurely. It 
should be set to one of the constants 
LDAP_OPT_ON or LDAP_OPT_OFF. This 
option is useful if an LDAP I/O operation is 
interrupted prematurely, (for example, by a 
timer going off) or other interrupt. 


Type for invalue parameter: int * 
Type for outvalue parameter: int * 


Description: This option indicates the 
version of the LDAP protocol used when 
communicating with the primary LDAP 
server. It must be one of the constants 
LDAP_VERSION2 (2) or LDAP_VERSION3 
(3). If no version is set, the default is 
LDAP_VERSION2 (2). 


Type for invalue parameter: LDAPControl 
2K 


Type for outvalue parameter: LDAPControl 
kK 


Description: A default list of LDAP server 
controls to be sent with each request. See 
Section 14.6 for more information. 


Type for invalue parameter: LDAPControl 
2K 


Type for outvalue parameter: LDAPControl 
2kKK 


Description: A default list of client 
controls that affect the LDAP session. 
See Section 14.6 for more information. 


Type for invalue parameter: char * 
Type for outvalue parameter: char ** 


Description: The host name (or list of host) 
for the primary LDAP server. 


Type for invalue parameter: int * 
Type for outvalue parameter: int * 


Description: The code of the most recent 
LDAP error that occurred for this session. 


Type for invalue parameter: char * 
Type for outvalue parameter: char ** 


Description: The message returned with 
the most recent LDAP error that occurred 
for this session. 


The address of a place to put the value of the option. The actual type of this 
parameter depends on the setting of the option parameter. For outvalues of 
type char ** and LDAPControl **, a pointer to data that is associated with the 
LDAP session Id is returned; callers should dispose of the memory by calling 
ldap_memfree() or ldap controls free(). 
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invalue A pointer to the value the option is to be given. The actual type of this 
parameter depends on the setting of the option parameter. The constants 
LDAP_OPT_ON and LDAP_OPT_OFF can be given for options that have on or 
off settings. 


Both ldap _get_option() and ldap set_option() return 0 if successful 
and -1 if an error occurs. 


14.6 Working with Controls 


LDAPv3 operations can be extended through the use of controls. Controls may be 
sent to a server or returned to the client with any LDAP message. These controls 
are referred to as server controls. 


The LDAP API also supports a client-side extension mechanism through the use 
of client controls. These controls affect the behavior of the LDAP API only and 
are never sent to a server. A common data structure is used to represent both 
types of controls: 


typedef struct ldapcontrol { 


char *ldctl_oid; 
struct berval ldctl_ value; 
char ldctl_iscritical; 


} LDAPControl, *PLDAPControl; 
The fields in the Idapcontrol structure have the following meanings: 


Idctl_oid The control type, represented as a string. 


Idctl_value The data associated with the control (if any). To specify a zero-length 
value, set Idctl_value.bv_len to zero and Idctl_value.bv_val to a zero- 
length string. To indicate that no data is associated with the control, 
set Idctl_value.bv_val to NULL. 


Idctl_iscritical Indicates whether the control is critical or not. If this field is non-zero, 
the operation will only be carried out if the control is recognized by the 
server and/or client. 


Some LDAP API calls allocate an Idapcontrol structure or a NULL-terminated 
array of Idapcontrol structures. The following functions can be used to dispose of 
a single control or an array of controls: 


void ldap control free( LDAPControl *ctrl ); 
void ldap controls free( LDAPControl **ctrls ); 


A set of controls that affect the entire session can be set using the 
ldap set _option() function. A list of controls can also be passed directly 

to some LDAP API calls, such as ldap_search_ext(), in which case any controls 
set for the session through the use of ldap _set_option() are ignored. Control 
lists are represented as a NULL-terminated array of pointers to Idapcontrol 
structures. 


Server controls are defined by LDAPv3 protocol extension documents; for 
example, a control has been proposed to support paging of search results. No 
client controls are currently implemented in this version of the API. 
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14.7 Authenticating to the Directory 


The following functions are used to authenticate an LDAP client to an LDAP 
directory server. 


The ldap _sasl_bind() and ldap sasl bind_s() functions can be used to do 
general and extensible authentication over LDAP through the use of the Simple 
Authentication Security Layer. The functions both take the DN to bind as, 

the method to use, as a dotted-string representation of an OID identifying the 
method, and a struct berval holding the credentials. The special constant value 
LDAP_SASL_ SIMPLE (NULL) can be passed to request simple authentication, or 
the simplified functions ldap_simple bind() or ldap simple bind_s() can be 


used. 


int ldap_sasl_bind( 


LDAP *ld, 
const char *dn, 
const char *mechanism, 
const struct berval *cred, 
LDAPControl *kserverctrls, 
LDAPControl **clientctrls, 
int *msgidp 
)i 
int ldap_sasl_bind_s( 
LDAP *ld, 
const char *dn, 
const char *mechanism, 
const struct berval *cred, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
struct berval **servercredp 
)i 
int ldap_simple bind( 
LDAP *ld, 
const char *dn, 
const char *passwd 
3 
int ldap_simple bind s( 
LDAP *1d, 
const char *dn, 
*passwd 


const char 


) v 


The use of the following functions is deprecated: 


int ldap bind( LDAP *ld, char *dn, char *cred, int method ); 
int ldap bind_s( LDAP *ld, char *dn, char *cred, int method ); 


Parameters are as follows: 


Id The session handle. 

dn The name of the entry to bind as. 

mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentication, or 
a text string identifying the SASL method. 

cred The credentials with which to authenticate. Arbitrary credentials 


can be passed using this parameter. The format and content of the 
credentials depends on the setting of the mechanism parameter. 
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passwd For ldap simple bind(), the password to compare to the entry’s 
userPassword attribute. 

serverctrls List of LDAP server controls. 

clientctrls List of client controls. 

msgidp This result parameter will be set to the message id of the request if the 


ldap _sasl_bind() call succeeds. 


servercredp This result parameter will be filled in with the credentials passed back 
by the server for mutual authentication, if given. An allocated berval 
structure is returned that should be disposed of by calling ber_bvfree( ). 
NULL may be passed to ignore this field. 


Additional parameters for the deprecated functions are not described. See the 
RFC 1823 documentation for more information. 


The ldap_sasl_bind() function initiates an asynchronous bind operation and 
returns the constant LDAP_SUCCESS if the request was successfully sent or 
another LDAP error code if not. See Section 14.18 for more information about 
possible errors and how to interpret them. If successful, ldap_sasl_bind() places 
the message id of the request in *msgidp. A subsequent call to ldap_result ( ) 
can be used to obtain the result of the bind. 


The ldap_simple bind() function initiates a simple asynchronous bind operation 
and returns the message id of the operation initiated. A subsequent call to 

ldap result () can be used to obtain the result of the bind. In case of error, 
ldap simple bind() will return -1, setting the session error parameters in the 
LDAP structure appropriately. 


The synchronous ldap sasl_ bind_s() and ldap simple bind s() functions 

both return the result of the operation, either the constant LDAP_SUCCESS 

if the operation was successful, or another LDAP error code if it was not. See 
Section 14.18 for more information about possible errors and how to interpret 
them. 


Note that if an LDAP Version 2 server is contacted, no other operations over the 
connection should be attempted before a bind call has successfully completed. 


Subsequent bind calls can be used to reauthenticate over the same connection, 
and multistep SASL sequences can be accomplished through a sequence of calls 
to ldap _sasl bind() or ldap sasl bind s(). 


14.8 Closing the Session 


The following functions are used to unbind from the directory, close the 
connection, and dispose of the session handle. 


int ldap_unbind( LDAP *1d ); 
int ldap_unbind_s( LDAP *ld ); 


Parameter is as follows: 
Id The session handle. 


The ldap_unbind() and ldap unbind_s() functions both work synchronously, 
unbinding from the directory, closing the connection, and freeing up the Id 
structure before returning. There is no server response to an unbind operation. 
The ldap unbind() function returns LDAP_SUCCESS (or another LDAP 
error code if the request cannot be sent to the LDAP server). After a call to 
ldap unbind() or ldap _unbind_s(), the session handle Id is invalid and it is 
illegal to make any further LDAP API calls using Id. 
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14.9 Searching 


The following functions are used to search the LDAP directory, returning a 
requested set of attributes for each entry matched. There are five variations. 


int ldap_search_ext ( 
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LDAP *1d, 
const char *base, 
int scope, 
const char *filter, 
char **eattrs, 
int attrsonly, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
struct timeval *timeout, 
int sizelimit, 
int *msgidp 

i 

int ldap search _ext_s( 
LDAP *1d, 
const char *base, 
int scope, 
const char *filter, 
char **eattrs, 
int attrsonly, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
struct timeval *timeout, 
int sizelimit, 
LDAPMessage **res 

i 

int ldap_search ( 
LDAP *1d, 
const char *base, 
int scope, 
const char *filter, 
char **attrs, 
int attrsonly 

ie 

int ldap_search_s( 
LDAP *1d, 
const char *base, 
int scope, 
const char *filter, 
char **eattrs, 
int attrsonly, 
LDAPMessage **res 

i 

int ldap_search_st ( 
LDAP *1d, 
char *base, 
int scope, 
char *filter, 
char **eattrs, 
int attrsonly, 
struct timeval *timeout, 
LDAPMessage **res 


iy 
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Parameters are as follows: 


Id The session handle. 

base The dn of the entry at which to start the search. 

scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL 
(0x01), or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the 
search. 

filter A character string representing the search filter. The value NULL can 


be passed to indicate that the filter (objectclass=*) that matches all 
entries should be used. 


attrs A NULL-terminated array of strings indicating which attributes to 
return for each matching entry. Passing NULL for this parameter 
causes all available user attributes to be retrieved. The special 
constant string LDAP_NO_ATTRS (1.1) can be used as the only 
element in the array to indicate that no attribute types should be 
returned by the server. The special constant string LDAP_ALL_USER_ 
ATTRS (*), can be used in the attrs array along with the names of some 
operational attributes to indicate that all user attributes plus the listed 
operational attributes should be returned. 


attrsonly A boolean value that should be either zero if both attribute types and 
values are to be returned or non-zero if only types are wanted. 


timeout For the ldap_search_st() function, this specifies the local search 
timeout value (if it is NULL, the timeout is infinite). For the 
ldap search ext() and ldap search ext s() functions, this 
specifies both the local search timeout value and the operation time 
limit that is sent to the server within the search request. For the 
ldap search ext() and ldap search ext _s() functions, passing 
a NULL value for timeout causes the global default timeout stored in 
the LDAP session handle to be used (set using ldap set option() 
with the LDAP_OPT_TIMELIMIT parameter). 


sizelimit For the ldap search ext() and ldap search ext_s() calls, this 
is a limit on the number of entries to return from the search. A value 
of LDAP_NO_LIMIT (0) means no limit. 


res For the synchronous calls, this is a result parameter which will contain 
the results of the search upon completion of the call. 


serverctrls List of LDAP server controls. 
clientctris List of client controls. 
msgidp This result parameter will be set to the message id of the request if the 


ldap search _ext() call succeeds. 


There are three options in the session handle Id that potentially affect how the 
search is performed. They are as follows: 


LDAP_OPT_SIZELIMIT A limit on the number of entries to return from the 
search. A value of LDAP_NO_LIMIT (0) means no 
limit. Note that the value from the session handle 
is ignored when using the ldap search ext() or 
ldap search ext_s() functions. 


LDAP_OPT_TIMELIMIT A limit on the number of seconds to spend on the 
search. A value of LDAP_NO_LIMIT (0) means no 
limit. Note that the value from the session handle 
is ignored when using the ldap search ext() or 
ldap search ext_s() functions. 
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LDAP_OPT_DEREF One of LDAP_DEREF_NEVER(0x00), LDAP_DEREF_ 
SEARCHING(0x01), LDAP_DEREF_FINDING (0x02), or 
LDAP_DEREF_ALWAYS (0x03), specifying how aliases 
should be handled during the search. The LDAP_DEREF_ 
SEARCHING value means aliases should be dereferenced 
during the search but not when locating the base object 
of the search. The LDAP_DEREF_FINDING value means 
aliases should be dereferenced when locating the base 
object but not during the search. 


The ldap_search_ext() function initiates an asynchronous search operation and 
returns either the constant LDAP_SUCCESS if the request was successfully sent 
or another LDAP error code if not. See Section 14.18 for more information about 
possible errors and how to interpret them. If successful, ldap search ext ( ) 
places the message id of the request in *msgidp. A subsequent call to 

ldap result () can be used to obtain the results from the search. These results 
can be parsed using the result parsing functions described in Section 14.18. 


Similar to ldap search ext(), the ldap _search() function initiates an 
asynchronous search operation and returns the message id of the operation 
initiated. As for ldap search ext(), a Subsequent call to ldap result() can 
be used to obtain the result of the search. In case of error, ldap_search( ) 
will return -1, setting the session error parameters in the LDAP structure 
appropriately. 


The synchronous ldap search ext_s(), ldap search _s(), and 

ldap search _st() functions all return the result of the operation, either 

the constant LDAP_SUCCESS if the operation was successful or another LDAP 
error code if it was not. See Section 14.18 for more information about possible 
errors and how to interpret them. Entries returned from the search (if any) are 
contained in the res parameter. This parameter is opaque to the caller. Entries, 
attributes, and values should be extracted by calling the parsing functions. 
The results contained in res should be freed when no longer in use by calling 
ldap _msgfree(). 


The ldap search ext() and ldap search ext_s() functions support LDAPv3 
server controls, client controls, and allow varying size and time limits to be easily 
specified for each search operation. The ldap search _st() function is identical 
to ldap search_s() except that it takes an additional parameter specifying a 
local timeout for the search. The local search timeout is used to limit the amount 
of time the API implementation will wait for a search to complete. After the local 
search timeout the search operation will return LDAP_TIMEOUT if the search 
result has not been removed. 


14.9.1 Reading and Listing the Children of an Entry 


LDAP does not support a read operation directly. Instead, this operation is 
emulated by a search with base set to the DN of the entry to read, scope set 
to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or NULL. The attrs 
parameter contains the list of attributes to return. 


LDAP does not support a list operation directly. Instead, this operation is 
emulated by a search with base set to the DN of the entry to list, scope set to 
LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or NULL. The attrs 
parameter contains the list of attributes to return for each child entry. 
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14.10 Comparing a Value Against an Entry 


The following functions are used to compare a given attribute value assertion 


against an LDAP entry. There are four variations. 


int ldap_compare_ext ( 


LDAP *l1d, 
const char *dn, 
const char *xattr, 
const struct berval *bvalue 
LDAPControl *kserverctrls, 
LDAPControl **clientctrls, 
int *msgidp 
)i 
int ldap_compare ext_s( 
LDAP *1d, 
const char *dn, 
const char *attr, 
const struct berval *bvalue, 
LDAPControl *kserverctrls, 
LDAPControl **clientctrls 
i 
int ldap_compare ( 
LDAP *1d, 
const char *dn, 
const char ‘attr, 
const char *value 
i 
int ldap_compare_s( 
LDAP *1d, 
const char *dn, 
const char ‘attr, 
const char *value 


); 
Parameters are as follows: 


Id 

dn 

attr 
bvalue 


value 


serverctrls 
clientctrlis 
msgidp 


The session handle. 
The name of the entry to compare against. 
The attribute to compare against. 


The attribute value to compare against those found in the given entry. 
This parameter is used in the extended functions and is a pointer toa 
struct berval so it is possible to compare binary values. 


A string attribute value to compare against, used by the 
ldap_compare() and ldap compare _s() functions. Use 

ldap compare ext() or ldap compare ext_s() if you need to 
compare binary values. 


List of LDAP server controls. 
List of client controls. 


This result parameter will be set to the message id of the request if the 
ldap compare ext() call succeeds. 


The ldap_compare_ext() function initiates an asynchronous compare 

operation and returns either the constant LDAP_SUCCESS if the request 

was successfully sent, or another LDAP error code if not. See Section 14.18 

for more information about possible errors and how to interpret them. If 
successful, ldap compare ext() places the message id of the request in *msgidp. 
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A subsequent call to ldap_result() can be used to obtain the result of the 
compare. 


Similar to ldap compare ext(), the ldap_compare() function initiates an 
asynchronous compare operation and returns the message id of the operation 
initiated. As for ldap compare ext(), a subsequent call to ldap result() can 
be used to obtain the result of the compare. In case of error, ldap compare ( ) 
will return -1, setting the session error parameters in the LDAP structure 
appropriately. 


The synchronous ldap compare ext_s() and ldap compare _s() functions both 
return the result of the operation, either the constants LDAP_COMPARE_TRUE 
or LDAP_COMPARE_FALSE if the operation was successful, or another LDAP 
error code if it was not. See Section 14.18 for more information about possible 
errors and how to interpret them. 


The ldap_compare ext() and ldap compare ext_s() functions support LDAPv3 
server controls and client controls. 
14.11 Modifying an Entry 


The following functions are used to modify an existing LDAP entry. There are 
four variations. 


typedef struct ldapmod { 


int mod_op; 
char *mod_type; 
union { 
char *kmodv_strvals; 
struct berval **modv_bvals; 
} mod_vals; 
} LDAPMod; 
#define mod_values mod_vals.modv_strvals 
#define mod_bvalues mod_vals.modv_bvals 
int ldap modify ext ( 
LDAP *l1d, 
const char *dn, 
LDAPMod **mods, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
int *msgidp 


yi 
int ldap modify ext_s( 


LDAP *ld, 

const char *dn, 

LDAPMod **mods, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls 


di 
int ldap modify ( 


LDAP *1d, 
const char *dn, 
LDAPMod *kmods 


Mi 
int ldap_modify s( 


LDAP *1d, 
const char *dn, 
LDAPMod **mods 
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Parameters are as follows: 


Id The session handle. 

dn The name of the entry to modify. 

mods A NULL-terminated array of modifications to make to the entry. 
serverctrls List of LDAP server controls. 

clientctrls List of client controls. 

msgidp This result parameter will be set to the message id of the request if the 


ldap modify ext() call succeeds. 
The fields in the LDAPMod structure have the following meanings: 


mod_op The modification operation to perform. It should be one of LDAP_ 
MOD_ADD(0x00), LDAP_MOD_DELETE (0x01), or LDAP_MOD_ 
REPLACE (0x02). This field also indicates the type of values included 
in the mod_vals union. It is logically ORed with LDAP_MOD_ 
BVALUES (0x80) to select the mod_bvalues form. Otherwise, the 
mod_values form is used. 


mod_type The type of the attribute to modify. 


mod_vals The values (if any) to add, delete, or replace. Only one of the mod_ 
values or mod_bvalues variants should be used, selected by ORing 
the mod_op field with the constant LDAP_MOD_BVALUES. The mod_ 
values field is a NULL-terminated array of zero-terminated strings and 
mod_bvalues is a NULL- terminated array of berval structures that 
can be used to pass binary values such as images. 


For LDAP_MOD_ADD modifications, the given values are added to the entry, 
creating the attribute if necessary. 


For LDAP_MOD_DELETE modifications, the given values are deleted from the 
entry, removing the attribute if no values remain. If the entire attribute is to be 
deleted, the mod_vals field should be set to NULL. 


For LDAP_MOD_REPLACE modifications, the attribute will have the listed 
values after the modification, having been created if necessary, or removed if the 
mod_vals field is NULL. All modifications are performed in the order in which 
they are listed. 


The ldap modify ext() function initiates an asynchronous modify operation and 
returns the constant LDAP_SUCCESS if the request was successfully sent, or 
another LDAP error code if not. See Section 14.18 for more information about 
possible errors and how to interpret them. If successful, ldap_ modify ext () 
places the message id of the request in *msgidp. A subsequent call to 

ldap result () can be used to obtain the result of the modify. 


Similar to ldap modify _ext(), the ldap modify() function initiates an 
asynchronous modify operation and returns the message id of the operation 
initiated. As for ldap modify ext(), a subsequent call to ldap result () can 
be used to obtain the result of the modify. In case of error, ldap modify () 
will return -1, setting the session error parameters in the LDAP structure 
appropriately. 


The synchronous ldap modify ext _s() and ldap modify _s() functions both 
return the result of the operation, either the constant LDAP_SUCCESS if the 
operation was successful, or another LDAP error code if it was not. 


See Section 14.18 for more information about possible errors and how to interpret 
them. 
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The ldap modify ext() and ldap modify ext _s() functions support LDAPv3 
server controls and client controls. 


14.12 Modifying the Name of an Entry 


In LDAP Version 2, the ldap _modrdn() and ldap _modrdn_s() functions were 
used to change the name of an LDAP entry. They could only be used to change 
the least significant component of a name (the RDN or relative distinguished 
name). LDAPv3 provides the Modify DN protocol operation that allows more 
general name change access. The ldap rename() and ldap_rename_s() functions 
are used to change the name of an entry, and the use of the ldap _modrdn() and 
ldap _modrdn_s() functions is deprecated. 


int ldap_rename ( 


LDAP *ld, 
const char *dn, 
const char *newrdn, 
const char *newparent, 
int deleteoldrdn, 
LDAPControl *kserverctrls, 
LDAPControl **clientctrls, 
int *msgidp 
ie 
int ldap_rename_s( 
LDAP *ld, 
const char *dn, 
const char *newrdn, 
const char *newparent, 
int deleteoldrdn, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls 
Vj 
Use of the following functions is deprecated. 
int ldap _modrdn ( 
LDAP *ld, 
char *dn, 
char *newrdn, 
int deleteoldrdn 
i 
int ldap_modrdn_s( 
LDAP *ld, 
char *dn, 
char *newrdn, 
int deleteoldrdn 
yy 
Parameters are as follows: 
Id The session handle. 
dn The name of the entry whose DN is to be changed. 
newrdn The new RDN to give the entry. 
newparent The new parent, or superior entry. If this parameter is NULL, only 


the RDN of the entry is changed. The root DN may be specified by 
passing a zero length string, "". The newparent parameter should 
always be NULL when using Version 2 of the LDAP protocol; otherwise 


the server’s behavior is undefined. 
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deleteoldrdn This parameter only has meaning on the rename functions if newrdn 
is different than the old RDN. It is a boolean value. If it is non-zero, 
it indicates that the old RDN value(s) should be removed. If it is 
zero, it indicates that the old RDN value(s) should be retained as 
non-distinguished values of the entry. 


serverctrls List of LDAP server controls. 
clientctris List of client controls. 
msgidp This result parameter will be set to the message id of the request if the 


ldap rename () call succeeds. 


The ldap_rename() function initiates an asynchronous modify DN operation 
and returns the constant LDAP_SUCCESS if the request was successfully sent, 
or another LDAP error code if not. See Section 14.18 for more information 
about possible errors and how to interpret them. If successful, ldap rename ( ) 
places the DN message id of the request in *msgidp. A subsequent call to 
ldap result () can be used to obtain the result of the rename. 


The synchronous ldap _rename_s() returns the result of the operation, either the 
constant LDAP_SUCCESS if the operation was successful, or another LDAP error 
code if it was not. See Section 14.18 for more information about possible errors 
and how to interpret them. 


The ldap_rename() and ldap rename_s() functions both support LDAPv3 server 
controls and client controls. 
14.13 Adding an Entry 


The following functions are used to add entries to the LDAP directory. There are 
four variations. 


int ldap_add_ext ( 


LDAP *1d, 

const char *dn, 

LDAPMod **kattrs, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
int *msgidp 


di 
int ldap_add_ext_s( 


LDAP *1d, 

const char *dn, 

LDAPMod **attrs, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls 


)i 
int ldap add( 


LDAP *1d, 
const char *dn, 
LDAPMod **attrs 
i 
int ldap _add_s( 
LDAP *1d, 
const char *dn, 
LDAPMod **attrs 
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Parameters are as follows: 


Id The session handle. 
dn The name of the entry to add. 
attrs The entry's attributes, specified using the LDAPMod structure defined 


for ldap_modify(). The mod_type and mod_vals fields should be 
filled in. The mod_op field is ignored unless ORed with the constant 
LDAP_MOD_BVALUES, used to select the mod_bvalues case of the 
mod_vals union. 


serverctrls List of LDAP server controls. 
clientctris List of client controls. 
msgidp This result parameter will be set to the message id of the request if the 


ldap_add_ext() call succeeds. 


Note that the parent of the entry being added must already exist or the parent 
must be empty (that is, equal to the root DN) for an add to succeed. 


The ldap_add_ext() function initiates an asynchronous add operation and 
returns either the constant LDAP_SUCCESS if the request was successfully sent 
or another LDAP error code if not. See Section 14.18 for more information about 
possible errors and how to interpret them. If successful, ldap_add_ext() places 
the message id of the request in *msgidp. A subsequent call to ldap result ( ) 
can be used to obtain the result of the add. 


Similar to ldap _add_ext(), the ldap add() function initiates an asynchronous 
add operation and returns the message id of the operation initiated. As for 
ldap _add_ext (), a subsequent call to ldap result () can be used to obtain the 
result of the add. In case of error, ldap _add() will return -1, setting the session 
error parameters in the LDAP structure appropriately. 


The synchronous ldap_add_ext_s() and ldap _add_s() functions both return the 
result of the operation, either the constant LDAP_SUCCESS if the operation was 
successful, or another LDAP error code if it was not. See Section 14.18 for more 
information about possible errors and how to interpret them. 


The ldap add_ext() and ldap _add_ext_s() functions support LDAPv3 server 
controls and client controls. 
14.14 Deleting an Entry 


The following functions are used to delete a leaf entry from the LDAP directory. 
There are four variations. 


int ldap delete ext ( 


LDAP *1d, 

const char *dn, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
int *msgidp 


di 
int ldap delete ext_s( 


LDAP *1d, 
const char *dn, 
LDAPControl *kserverctrls, 
LDAPControl **clientctrls 


i 


int ldap delete ( 
LDAP *1d, 
const char *dn 


Me 
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int ldap_delete_s( 
LDAP *1d, 
const char *dn 


); 
Parameters are as follows: 


Id The session handle. 

dn The name of the entry to delete. 

serverctrls List of LDAP server controls. 

clientctrls List of client controls. 

msgidp This result parameter will be set to the message id of the request if the 


ldap_delete _ext() call succeeds. 


Note that the entry to delete must be a leaf entry (that is, it must have no 
children). Deletion of entire subtrees in a single operation is not supported by 
LDAP. 


The ldap delete ext() function initiates an asynchronous delete operation and 
returns either the constant LDAP_SUCCESS if the request was successfully sent 
or another LDAP error code if not. See Section 14.18 for more information about 
possible errors and how to interpret them. If successful, ldap delete ext () 
places the message id of the request in *msgidp. A subsequent call to 

ldap result () can be used to obtain the result of the delete. 


Similar to ldap delete ext(), the ldap delete() function initiates an 
asynchronous delete operation and returns the message id of the operation 
initiated. As for ldap delete ext (), a subsequent call to ldap result () can be 
used to obtain the result of the delete. In case of error, ldap _delete() will return 
-1, setting the session error parameters in the LDAP structure appropriately. 


The synchronous ldap delete ext_s() and ldap delete _s() functions both 
return the result of the operation, either the constant LDAP_SUCCESS if 
the operation was successful or another LDAP error code if it was not. See 
Section 14.18 for more information about possible errors and how to interpret 
them. 


The ldap delete ext() and ldap delete ext _s() functions support LDAPv3 
server controls and client controls. 


14.15 Extended Operations 


The ldap_extended_operation() and ldap extended _operation_s() functions 
allow extended LDAP operations to be passed to the server, providing a general 
protocol extensibility mechanism. 


int ldap_extended_operation ( 


LDAP *1ld, 

const char *requestoid, 
const struct berval *request data, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
int *msgidp 
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int ldap_extended_operation_s( 


LDAP *1d, 

const char *requestoid, 
const struct berval *request data, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
char **retoidp, 
struct berval **retdatap 


); 
Parameters are as follows: 


Id The session handle. 

requestoid The dotted-Ol D text string naming the request. 

requestdata The arbitrary data required by the operation (if NULL, no data is sent 
to the server). 

serverctrls List of LDAP server controls. 

clientctrlis List of cient controls. 

msgidp This result parameter will be set to the message id of the request if the 
ldap _extended_operation() call succeeds. 

retoidp Pointer to a character string that will be set to an allocated, dotted- 


OID text string returned by the server. This string should be disposed 
of using the ldap_memfree() function. If no OID was returned, 
*retoidp is set to NULL. 


retdatap Pointer to a berval structure pointer that will be set to an allocated 
copy of the data returned by the server. This struct berval should be 
disposed of using ber_bvfree(). If no data is returned, *retdatap is set 
to NULL. 


The ldap_extended_operation() function initiates an asynchronous extended 
operation and returns either the constant LDAP_SUCCESS if the request was 
successfully sent or another LDAP error code if not. See Section 14.18 for more 
information about possible errors and how to interpret them. If successful, 
ldap extended _operation() places the message id of the request in *msgidp. 
A subsequent call to ldap result () can be used to obtain the result of the 
extended operation which can be passed to ldap parse extended _result() to 
obtain the OID and data contained in the response. 


The synchronous ldap _extended_operation_s() function returns the result 

of the operation, either the constant LDAP_SUCCESS if the operation was 
successful or another LDAP error code if it was not. See Section 14.18 for more 
information about possible errors and how to interpret them. The retoid and 
retdata parameters are filled in with the OID and data from the response. If no 
OID or data was returned, these parameters are set to NULL. 


The ldap_extended_operation() and ldap extended_operation_s() functions 
both support LDAP v3 server controls and client controls. 

14.16 Abandoning an Operation 
The following calls are used to abandon an operation in progress: 


int ldap _abandon_ext ( 


LDAP *ld, 

int msgid, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls 
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int ldap_abandon ( 
LDAP *1d, 
int msgid 
di 


Parameters are as follows: 


Id The session handle. 

msgid The message id of the request to be abandoned. 
serverctrls List of LDAP server controls. 

clientctrls List of client controls. 


The ldap_abandon_ext() function abandons the operation with message id msgid 
and returns either the constant LDAP_SUCCESS if the abandon was successful 
or another LDAP error code if not. See Section 14.18 for more information about 
possible errors and how to interpret them. 


The ldap_abandon() function is identical to ldap abandon _ext() except that it 
does not accept client or server controls and it returns zero if the abandon was 

successful, -1 otherwise and does not support LDAPv3 server controls or client 

controls. 


After a successful call to ldap abandon() or ldap abandon _ext(), results 
with the given message id are never returned from a subsequent call to 
ldap result (). Thereis no server response to LDAP abandon operations. 


14.17 Obtaining Results and Looking Inside LDAP Messages 


The ldap result () function is used to obtain the result of a previous 
asynchronously initiated operation. Note that depending on how it is called, 
ldap result () may actually return a list or "chain" of result messages. Once 
a chain of messages has been returned to the caller, it is no longer tied in any 
caller-visible way to the LDAP request that produced it. Therefore, a chain 

of messages returned by calling ldap result () or by calling a synchronous 
search function will never be affected by subsequent LDAP API calls (except for 
ldap_msgfree(), which is used to dispose of a chain of messages). 


The ldap_msgfree() function frees the result messages (possibly an entire chain 
of messages) obtained from a previous call to ldap result () or froma call toa 
synchronous search function. 


The ldap _msgtype() function returns the type of an LDAP message. The 
ldap _msgid() function returns the message 1D of an LDAP message. 


int ldap_result ( 


LDAP 1d, 

int msgid, 
int all, 
struct timeval *timeout, 
LDAPMessage **res 


di 

int ldap_msgfree( LDAPMessage *res ); 
int ldap_msgtype( LDAPMessage *res ); 
int ldap_msgid( LDAPMessage *res )j; 
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Parameters are as follows: 


Id The session handle. 

msgid The message id of the operation whose results are to be returned, or 
the constant LDAP_RES_ANY (-1) if any result is desired. 

all Specifies how many messages will be retrieved in a single call to 


ldap_result(). This parameter only has meaning for search results. 
Pass the constant LDAP_MSG ONE (0x00) to retrieve one message at 
atime. Pass LDAP_MSG ALL (0x01) to request that all results of a 
search be received before returning all results in a single chain. Pass 
LDAP_MSG_RECEIVED (0x02) to indicate that all results retrieved so 
far should be returned in the result chain. 


timeout A timeout specifying how long to wait for results to be returned. 
A NULL value causes ldap result () to block until results are 
available. A timeout value of zero seconds specifies a polling behavior. 


res For ldap result (),a result parameter that will contain the result(s) 
of the operation. For ldap _msgfree(), the result chain to be freed, 
obtained from a previous call to ldap result(), ldap search s(), 
or ldap search st(). 


Upon successful completion, ldap_result() returns the type of the first result 
returned in the res parameter. This will be one of the following constants. 


LDAP RES BIND (0x61) 

LDAP RES SEARCH ENTRY (0x64) 

LDAP _RES SEARCH REFERENCE (0x73) -- new in LDAPv3 
LDAP RES SEARCH RESULT (0x65) 

LDAP _RES MODIFY (0x67) 

LDAP_RES ADD (0x69) 


LDAP_RES DELETE (0x6B) 

LDAP RES MODDN (0xé6D) 

LDAP _RES COMPARE (0x6F) 

LDAP RES EXTENDED (0x78) -- new in LDAPv3 


The ldap_result() function returns 0 if the timeout expired and -1 if an error 
occurs, in which case the error parameters of the LDAP session handle will be set 
accordingly. 


The ldap_msgfree() function frees the result structure pointed to by res and 
returns the type of the message it freed. 


The ldap_msgtype() function returns the type of the LDAP message it is passed 
as a parameter. The type will be one of the types listed above, or -1 on error. 


The ldap _msgid() function returns the message ID associated with the LDAP 
message passed as a parameter. 


14.18 Handling Errors and Parsing Results 


The following calls are used to extract information from results and 

handle errors returned by other LDAP API functions. Note that 

ldap parse sasl bind result() and ldap parse extended result() must 
typically be used in addition to ldap parse result() to retrieve all the result 
information from SASL bind and extended operations, respectively. 
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int ldap parse result ( 


LDAP *1d, 
LDAPMessage *res, 
int *errcodep, 
char **matcheddnp, 
char *kerrmsgp, 
char ***referralsp, 
LDAPControl ***serverctrisp, 
int freeit 

i 

int ldap parse sasl bind result ( 
LDAP *1d, 
LDAPMessage *res, 
struct berval **servercredp, 
int freeit 

ee 

int ldap parse extended result ( 
LDAP *1d, 
LDAPMessage *res, 
char **resultoidp, 
struct berval **resultdata, 
int freeit 

i 

char *ldap_err2string( int err ); 

The use of the following functions is deprecated. 

int ldap_result2error ( 
LDAP *1d, 
LDAPMessage *res, 
int freeit 


)i 


void ldap_perror( LDAP *ld, const char *msg ); 


Parameters are as follows: 


Id 
res 


errcodep 


matcheddnp 


errmsgp 


referralsp 


The session handle. 


The result of an LDAP operation as returned by ldap result() or 
one of the synchronous API operation calls. 


This result parameter will be filled in with the LDAP error code field 
from the LDAPMessage result. This is the indication from the server of 
the outcome of the operation. NULL may be passed to ignore this field. 


In the case of a return of LDAP_NO_SUCH_OB}J ECT, this result 
parameter will be filled in with a DN indicating how much of the 
name in the request was recognized. NULL may be passed to 
ignore this field. The matched DN string should be freed by calling 
ldap_memfree(). 


This result parameter will be filled in with the contents of the error 
message field from the LDAPMessage result. The error message string 
should be freed by calling ldap_memfree(). NULL may be passed to 
ignore this field. 


This result parameter will be filled in with the contents of the referrals 
field from the LDAPMessage result, indicating zero or more alternate 
LDAP servers where the request should be retried. The referrals array 
should be freed by calling ldap value free(). NULL may be passed 
to ignore this field. 
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serverctrlIsp This result parameter will be filled in with an allocated array of 
controls copied out of the LDAPMessage result. The control array 
should be freed by calling ldap_controls free(). 


freeit A boolean that determines whether or not the res parameter is disposed 
of. Pass any non-zero value to have these functions free res after 
extracting the requested information. This option is provided as a 
convenience; you can also use ldap msgfree() to free the result 
later. If freeit is non-zero, the entire chain of messages represented by 
res is disposed of. 


servercredp For SASL bind results, this result parameter will be filled in with 
the credentials passed back by the server for mutual authentication, 
if given. An allocated berval structure is returned that should be 
disposed of by calling ber_bvfree(). NULL may be passed to ignore this 
field. 


resultoidp For extended results, this result parameter will be filled in with 
the dotted-OID text representation of the name of the extended 
operation response. This string should be disposed of by calling 
ldap_memfree(). NULL may be passed to ignore this field. 


resultdatap For extended results, this result parameter will be filled in with a 
pointer to a struct berval containing the data in the extended operation 
response. It should be disposed of by calling ber_bvfree(). NULL may 
be passed to ignore this field. 


err For ldap err2string(), an LDAP error code, as returned by 
ldap parse result() or another LDAP API call. 


Additional parameters for the deprecated functions are not described. See RFC 
1823 for more information. 


All three of the ldap_parse_* result() functions skip over messages of 

type LDAP_RES SEARCH _ENTRY and LDAP_RES SEARCH REFERENCE 
when looking for a result message to parse. They return either the constant 
LDAP_SUCCESS if the result was successfully parsed or another LDAP error 
code if not. Note that the LDAP error code that indicates the outcome of the 
operation performed by the server is placed in the errcodep ldap parse result () 
parameter. If a chain of messages that contains more than one result message is 
passed to these functions, they always operate on the first result in the chain. 


The ldap_err2string() function is used to convert a numeric LDAP error code, 
as returned by either one of the three ldap parse * result () functions or one 
of the synchronous API operation calls, into an informative zero-terminated 

character string message describing the error. It returns a pointer to static data. 


14.18.1 Stepping Through a List of Results 


The ldap first message() and ldap next message() functions are used to step 
through the list of messages in a result chain returned by ldap result (). For 
search operations, the result chain may actually include referral messages, entry 
messages, and result messages. The ldap_count_messages() function is used to 
count the number of messages returned. The ldap_msgtype() function can be 
used to distinguish between the different message types. 


LDAPMessage *ldap first_message( LDAP *ld, LDAPMessage *res ); 
LDAPMessage *ldap next_message ( LDAP *ld, LDAPMesage *msg ) ; 
int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 
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Parameters are as follows: 


Id The session handle. 


res The result chain, as obtained by a call to one of the synchronous search 
functions or ldap _result(). 


msg The message returned by a previous call to ldap first _message() or 
ldap next _message(). 


The ldap first _message() and ldap next _message() functions will return 
NULL when no more messages exist in the result set to be returned. NULL is 
also returned if an error occurs while stepping through the entries, in which case 
the error parameters in the session handle Id will be set to indicate the error. 


The ldap_count_messages() function returns the number of messages contained 
in a chain of results. It can also be used to count the number of messages 

that remain in a chain if called with a message, entry, or reference returned 

by ldap first message(), ldap next message(), ldap first entry(), 

ldap _next_entry(), ldap first _reference(), ldap_next_reference(). 


14.19 Parsing Search Results 


The following calls are used to parse the entries and references returned by 
ldap_search(). These results are returned in an opaque structure that should 
only be accessed by calling the functions. Functions are provided to step through 
the entries and references returned, step through the attributes of an entry, 
retrieve the name of an entry, and retrieve the values associated with a given 
attribute in an entry. 


14.19.1 Stepping Through a List of Entries 


The ldap first entry() and ldap next _entry() functions are used to step 
through and retrieve the list of entries from a search result chain. The 

ldap _first_reference() and ldap next_reference() functions are used to 
step through and retrieve the list of continuation references from a search result 
chain. The ldap_count_entries() function is used to count the number of 
entries returned. The ldap_count_references() function is used to count the 
number of references returned. 


LDAPMessage *ldap first_entry( LDAP *ld, LDAPMessage *res ); 
LDAPMessage *ldap next _entry( LDAP *ld, LDAPMessage *entry ); 
LDAPMessage *ldap first _reference( LDAP *ld, LDAPMessage *res )j; 


LDAPMessage *ldap next _reference( LDAP *ld, LDAPMessage *ref )j; 
int ldap_count_entries( LDAP *ld, LDAPMessage *res ) j; 


int ldap_count_references( LDAP *ld, LDAPMessage ‘res ); 
Parameters are as follows: 


Id The session handle. 
res The search result, as obtained by a call to one of the synchronous search 
functions or ldap _result(). 
entry The entry returned by a previous call to ldap first entry() or 
ldap _next_entry(). 
The ldap first entry() and ldap next entry() functions will return NULL 
when no more entries or references exist in the result set to be returned. NULL 
is also returned if an error occurs while stepping through the entries, in which 
case the error parameters in the session handle Id will be set to indicate the error. 
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The ldap_count_entries() function returns the number of entries contained 
in a chain of entries. It can also be used to count the number of entries 
that remain in a chain if called with a message, entry or reference returned 
by ldap first message(), ldap next _message(), ldap first entry(), 
ldap next_entry(), ldap_first_reference(), ldap next_reference(). 


The ldap_count_references() function returns the number of references 
contained in a chain of search results. It can also be used to count the number of 
references that remain in a chain. 

14.19.2 Stepping Through the Attributes of an Entry 


The ldap _first_attribute() and ldap _next_attribute() calls are used to step 
through the list of attribute types returned with an entry. 


char *ldap first_attribute ( 


LDAP *1d, 
LDAPMessage *xentry, 
BerElement *eotr 


i 


char *ldap next_attribute ( 


LDAP *1d, 
LDAPMessage *xentry, 
BerElement *ptr 


yj 
void ldap_memfree( char *mem ) ; 
Parameters are as follows: 


Id The session handle. 


entry The entry whose attributes are to be stepped through, as returned by 
ldap first entry() or ldap next entry(). 


ptr In ldap first attribute (), the address of a pointer used internally to keep 
track of the current position in the entry. In ldap _next_attribute(), the 
pointer returned by a previous call to ldap first attribute(). 


mem A pointer to memory allocated by the LDAP library, such as the 
attribute type names returned by ldap _first_attribute() and 
ldap next attribute(),or the DN returned by ldap get dn(). 


The ldap first _attribute() and ldap next _attribute() functions will return 
NULL when the end of the attributes is reached, or if there is an error, in which 
case the error parameters in the session handle Id will be set to indicate the error. 


Both functions return a pointer to an allocated buffer containing the current 
attribute name. This should be freed when no longer in use by calling 
ldap_memfree(). 


The ldap first _attribute() function will allocate and return in ptr a pointer 
to a BerElement used to keep track of the current position. This pointer should 
be passed in subsequent calls to ldap next_attribute() to step through 

the entry's attributes. After a set of calls toldap first _attribute() and 
ldap next_attribute(), if ptr is non-NULL, it should be freed by calling 

ber _free(ptr, 0). Note that it is very important to pass the second parameter 
as 0 (zero) in this call, since the buffer associated with the BerElement does not 
point to separately allocated memory. 


The attribute type names returned are suitable for passing in a call to 
ldap_get_values() to retrieve the associated values. 
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14.19.3 Retrieving the Values of an Attribute 


The ldap get _values() and ldap get values len() functions are used to 

retrieve the values of a given attribute from an entry. The ldap count values () 
and ldap count values len() functions are used to count the returned values. 
The ldap value free() and ldap value free len() functions are used to free 


the values. 
char **ldap_get_values ( 
LDAP *1d, 
LDAPMessage *entry, 
char *attr 


)i 


struct berval **ldap_get_values_len( 


LDAP *l1d, 
LDAPMessage *xentry, 
char *attr 


)i 

int ldap_count_values( char **vals ) 

int ldap_count_values_len( struct berval **vals ); 
void ldap value _free( char **vals )j; 


void ldap value free len( struct berval **vals )j; 
Parameters are as follows: 


Id The session handle. 


entry The entry from which to retrieve values, as returned by ldap first entry() 
or ldap next entry(). 


attr The attribute whose values are to be retrieved, as returned by 
ldap first attribute() or ldap next attribute(), or a caller- 
supplied string (for example, "mail"). 


vals The values returned by a previous call to ldap get _values() or 
ldap get values len(). 


Two forms of the various calls are provided. The first form is only suitable for 
use with non-binary character string data. The second len form is used with any 
kind of data. 


The ldap_get_values() and ldap get values _len() functions return NULL if 
no values are found for attr or if an error occurs. 


The ldap_count values() and ldap count values _len() functions return -1 if 
an error occurs such as the vals parameter being invalid. 


Note that the values returned are dynamically allocated and should be freed by 
calling either ldap value _free() or ldap value free _len() when no longer in 
use. 


14.19.4 Retrieving the Name of an Entry 


The ldap _get_dn() function is used to retrieve the name of an entry. The 
ldap explode dn() and ldap explode rdn() functions are used to break up a 
name into its component parts. The ldap _dn2ufn() function is used to convert 
the name into a more user-friendly format. 
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char *ldap get _dn( LDAP *ld, LDAPMessage *entry ); 
char **ldap explode _dn( const char *dn, int notypes ); 
char **ldap explode _rdn( const char *rdn, int notypes ); 


char *ldap dn2ufn( const char *dn ); 


Parameters are as follows: 


Id The session handle. 

entry The entry whose name is to be retrieved, as returned by 
ldap first entry() or ldap next entry(). 

dn The dn to explode, such as returned by ldap _get_dn(). 

rdn The rdn to explode, such as returned in the components of the array 
returned by ldap explode dn(). 

notypes A boolean parameter, if non-zero indicating that the DN or RDN 


components should have their type information stripped off (i.e, 
"cn=Babs" would become "Babs"). 


The ldap_get_dn() function will return NULL if there is some error parsing 
the dn, setting error parameters in the session handle Id to indicate the error. It 
returns a pointer to newly allocated space that the caller should free by calling 
ldap _memfree() when it is no longer in use. 


The ldap_explode_dn() function returns a NULL-terminated char * array 
containing the RDN components of the DN supplied, with or without types as 
indicated by the notypes parameter. The components are returned in the order 
they appear in the dn. The array returned should be freed when it is no longer in 
use by calling ldap value free(). 


The ldap_explode_rdn() function returns a NULL-terminated char * array 
containing the components of the RDN supplied, with or without types as 
indicated by the notypes parameter. The components are returned in the order 
they appear in the rdn. The array returned should be freed when it is no longer 
in use by calling ldap value free(). 


The ldap _dn2ufn() function converts the DN into the user friendly format. 
The UFN returned is newly allocated space that should be freed by a call to 
ldap_memfree() when no longer in use. 
14.19.5 Retrieving Controls from an Entry 
The ldap_get entry _controls() function is used to extract LDAP controls from 


an entry. 
int ldap_get_entry controls ( 
LDAP *1d, 
LDAPMessage *xentry, 
LDAPControl *kkserverctrisp 


ee 
Parameters are as follows: 


Id The session handle. 


entry The entry to extract controls from, as returned by 
ldap first entry() or ldap next entry(). 
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serverctrlsp This result parameter will be filled in with an allocated array of 
controls copied out of entry. The control array should be freed by 
calling ldap_controls free(). If serverctrisp is NULL, no controls 
are returned. 


The ldap get entry controls() function returns an LDAP error code that 
indicates whether the reference could be successfully parsed (_.DAP_SUCCESS if 
all goes well). 

14.19.6 Parsing References 


The ldap parse reference() function is used to extract referrals and controls 
from a SearchResultReference message. 


int ldap_parse_ reference ( 


LDAP *1d, 

LDAPMessage *ref, 

char ***referralsp, 
LDAPControl *kkserverctrisp, 
int freeit 


)i 


Parameters are as follows: 


Id The session handle. 
ref The reference to parse, as returned by ldap result(), 

ldap first _reference(),or ldap next _reference(). 
referralsp This result parameter will be filled in with an allocated array of 


character strings. The elements of the array are the referrals (typically 
LDAP URLs) contained in ref. The array should be freed when no 
longer in used by calling ldap value free(). If referralsp is NULL, 
the referral URLs are not returned. 


serverctrlsp This result parameter will be filled in with an allocated array of 
controls copied out of ref. The control array should be freed by calling 
ldap controls free(). If serverctrisp is NULL, no controls are 
returned. 


freeit A boolean that determines whether or not the ref parameter is disposed 
of. Pass any non-zero value to have these functions free ref after 
extracting the requested information. This option is provided as a 
convenience; you can also use ldap msgfree() to free the result 
later. 


The ldap_parse_reference() function returns an LDAP error code that indicates 
whether the reference could be successfully parsed (_.DAP_SUCCESS if all goes 
well). 


14.20 Encoded ASN.1 Value Manipulation 


This section describes functions that may be used to encode and decode BER- 
encoded ASN.1 values, which are often used inside of control and extension 
values. 


The following additional integral types are defined for use in manipulation of 
BER encoded ASN.1 values: 


typedef unsigned long ber tag t; /* for BER tags */ 


typedef long ber int_t; /* for BER ints, enums, and Booleans */ 
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With the exceptions of two new functions, ber flatten() and ber init(), 
these functions are compatible with the University of Michigan LDAP 3.3 
implementation of BER. 


typedef struct berval { 


ber len t bv_len; 
char *bv_val; 
} BerValue; 


A struct berval contains a sequence of bytes and an indication of its length. The 
bv_val is not null terminated. A bv_len must always be a nonnegative number. 
Applications may allocate their own berval structures. 


typedef struct berelement { 
/* opaque */ 

} BerElement ; 
The BerElement structure contains not only a copy of the encoded value, but 
also state information used in encoding or decoding. Applications cannot allocate 
their own BerElement structures. The internal state is neither thread-specific 
nor locked, so two threads should not manipulate the same BerElement value 
simultaneously. 


A single BerElement value cannot be used for both encoding and decoding. 
void ber bvfree( struct berval *bv ); 


The ber _bvfree() function frees a berval returned from this API. Both the 
bv->bv_val string and the berval itself are freed. Applications should not use 
ber _bvfree() with bervals which the application has allocated. 


void ber bvecfree ( struct berval **bv ); 


The ber _bvecfree() function frees an array of bervals returned from this API. 
Each of the bervals in the array are freed using ber_bvfree(), then the array 
itself is freed. 


struct berval *ber bvdup (struct berval *bv ); 


The ber _bvdup() function returns a copy of a berval. The bv_val field in the 
returned berval points to a different area of memory as the bv_val field in the 
argument berval. The null pointer is returned on error (for example, out of 
memory). 


void ber free ( BerElement *ber, int fbuf ); 


The ber free() function frees a BerElement which is returned from the API 
calls ber alloc _t() or ber init(). Each BerElement must be freed by the 
caller. The second argument fbuf should always be set to 1 to ensure that the 
internal buffer used by the BER functions is freed as well as the BerElement 
container itself. 


14.20.1 Encoding 
The following is an example of encoding: 


BerElement *ber_alloc_t(int options) ; 


The ber alloc _t() function constructs and returns BerElement. The null 
pointer is returned on error. The options field contains a bitwise-or of options 
which are to be used when generating the encoding of this BerElement. One 
option is defined and must always be supplied: 


#define LBER_USE DER 0x01 
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When this option is present, lengths will always be encoded in the minimum 
number of octets. Note that this option does not cause values of sets and 
sequences to be rearranged in tag and byte order, so these functions are not 
sufficient for generating DER output as defined in X.509 and X.680. If the caller 
takes responsibility for ordering values of sets and sequences correctly, DER 
output as defined in X.509 and X.680 can be produced. 


Unrecognized option bits are ignored. 


The BerElement returned by ber alloc t() is initially empty. Calls to 
ber printf () will append bytes to the end of the BerElement. 


int ber printf(BerElement *ber, char *fmt, ... ) 


The ber_printf£() function is used to encode a BER element in much the same 
way that sprintf () works. One important difference, though, is that state 
information is kept in the BER argument so that multiple calls can be made 

to ber printf() to append to the end of the BER element. BER must bea 
pointer to a BerElement returned by ber_alloc_t(). The ber printf() function 
interprets and formats its arguments according to the format string fmt. The 
ber printf () function returns -1 if there is an error during encoding and a 
positive number if successful. As with sprintf (), each character in fmt refers to 
an argument to ber printf(). 


The format string can contain the following format characters: 


t Tag. The next argument is a ber tag _t specifying the tag to override the 
next element to be written to the ber. This works across calls. The value must 
contain the tag class, constructed bit, and tag value. The tag value must fit 
in a single octet (tag value is less than 32). For example, a tag of "[3]" for a 
constructed type is 0xA3. 


b Boolean. The next argument is a ber_int_t, containing either 0 for FALSE 
or Oxff for TRUE. A boolean element is output. If this format character is not 
preceded by the 't’ format modifier, the tag 0x01 is used for the element. 


e Enumerated. The next argument is a ber _int_t, containing the enumerated 
value in the host’s byte order. An enumerated element is output. If this format 
character is not preceded by the 't’ format modifier, the tag Ox0A is used for the 
element. 


i Integer. The next argument is a ber_int_t, containing the integer in the 
host's byte order. An integer element is output. If this format character is not 
preceded by the 't’ format modifier, the tag 0x02 is used for the element. 


B Bitstring. The next two arguments are a char * pointer to the start of the 
bitstring, followed by a ber len t containing the number of bits in the 
bitstring. A bitstring element is output, in primitive form. If this format 
character is not preceded by the 't’ format modifier, the tag 0x03 is used for the 
element. 


n Null. No argument is required. An ASN.1 NULL element is output. If this 
format character is not preceded by the 't’ format modifier, the tag 0x05 is used 
for the element. 


fe) Octet string. The next two arguments are a char *, followed by aber _ len t 
with the length of the string. The string may contain null bytes and need not 
by zero-terminated. An octet string element is output, in primitive form. If this 
format character is not preceded by the 't’ format modifier, the tag 0x04 is used 
for the element. 


Ss Octet string. The next argument is a char * pointing to a zero-terminated 
string. An octet string element in primitive form is output, which does not 
include the trailing \ 0’ byte. If this format character is not preceded by the 't’ 
format modifier, the tag 0x04 is used for the element. 
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V Several octet strings. The next argument is a char **, an array of char * 
pointers to zero-terminated strings. The last element in the array must bea 
null pointer. The octet strings do not include the leading SEQUENCE OF octet 
strings. The 't’ format modifier cannot be used with this format character. 


V Several octet strings. A NULL-terminated array of struct berval *’s is supplied. 
Note that a construct like ‘{V¥ is required to get an actual SEQUENCE OF 
octet strings. The ’t’ format modifier cannot be used with this format character. 


{ Begin sequence. No argument is required. If this format character is not 
preceded by the 't’ format modifier, the tag 0x30 is used. 
} End sequence. No argument is required. The 't’ format modifier cannot be used 


with this format character. 


[ Begin set. No argument is required. If this format character is not preceded by 
the 't’ format modifier, the tag 0x31 is used. 


] End set. No argument is required. The 't’ format modifier cannot be used with 
this format character. 


Each use of a '{ format character must be matched by a ’} character, either later 
in the format string, or in the format string of a subsequent call to ber printf () 
for that BerElement. The same applies to the ‘[’ and ’J’. 


Sequences and sets nest, and implementations of this API must maintain internal 
state to be able to properly calculate the lengths. 


int ber flatten (BerElement *ber, struct berval **bvPtr) ; 


The ber flatten() function allocates a struct berval whose contents are a BER 
encoding taken from the ber argument. The bvPtr pointer points to the returned 
berval, which must be freed using ber _bvfree(). This function returns 0 on 
success and -1 on error. 


The ber flatten() API call is not present in U-M LDAP 3.3. 


The use of ber flatten() on a BerElement in which all ’{ and ’} format 
modifiers have not been properly matched is an error (that is, -1 will be returned 
by ber flatten() if this situation is exists). 


14.20.1.1_ Encoding Example 
The following is an example of encoding the following ASN.1 data type: 


ExamplelRequest ::= SEQUENCE { 
Ss OCTET STRING, -- must be printable 
vall INTEGER, 
val2 [0] INTEGER DEFAULT 0 


} 


int encode_examplel(char *s,ber_int_t vall,ber int _t val2, 
struct berval **bvPtr) 


{ 


BerElement *ber; 
int rc; 


ber = ber alloc t(LBER USE DER); 


if (ber == NULL) return -1; 


if (ber _printf(ber,"{si",s,vall) == -1) { 
ber free (ber,1) ; 
return, =1; 
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(val2 != 0) { 

(ber printf (ber, "ti", (ber_tag_t)0x80,val2) == -1) { 
ber free (ber,1) ; 
return -1; 


} 


if 
if 


if (ber_printf£(ber,"}") == -1) { 
ber free (ber,1) ; 
return -1; 


re = ber flatten(ber,bvPtr) ; 
ber free (ber,1) ; 
return rc; 


14.20.2 Decoding 
The following two symbols are available to applications. 


#define LBER ERROR OxffffffffL 
#define LBER DEFAULT OxffffffffL 


BerElement *ber_ init (struct berval *bv) ; 


The ber_init() function constructs a BerElement and returns a new BerElement 
containing a copy of the data in the bv argument. The ber init () function 
returns the null pointer on error. 


ber tag_t ber_scanf (BerElement *ber, char *fmt, ... ); 


The ber_scanf () function is used to decode a BER element in much the same 
way that sscanf() works. One important difference, though, is that some state 
information is kept with the ber argument so that multiple calls can be made 

to ber_scanf () to sequentially read from the BER element. The ber argument 
must be a pointer to a BerElement returned by ber init(). The ber_scanf ( ) 
function interprets function the bytes according to the format string fmt, and 
stores the results in its additional arguments. The ber_scanf () function returns 
LBER_ERROR on error, and a different value on success. 


The format string contains conversion specifications which are used to direct the 
interpretation of the BER element. The format string can contain the following 
characters: 


a Octet string. A char ** argument should be supplied. Memory is allocated, 
filled with the contents of the octet string, null- terminated, and the pointer to 
the string is stored in the argument. The returned value must be freed using 
ldap_memfree(). The tag of the element must indicate the primitive form 
(constructed strings are not supported) but is otherwise ignored and discarded 
during the decoding. This format cannot be used with octet strings which could 
contain null bytes. 


O Octet string. A struct berval ** argument should be supplied, which upon 
return points to a allocated struct berval containing the octet string and its 
length. The ber_bvfree() function must be called to free the allocated 
memory. The tag of the element must indicate the primitive form (constructed 
strings are not supported) but is otherwise ignored during the decoding. 


b Boolean. A pointer toa ber int _t should be supplied. The value stored will 
be 0 for FALSE or nonzero for TRUE. The tag of the element must indicate the 
primitive form but is otherwise ignored during the decoding. 
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e Enumerated value stored will be in host byte order. The tag of the element 
must indicate the primitive form but is otherwise ignored during the decoding. 
The ber_scanf () function will return an error if the enumerated value cannot 
be stored in aber int t. 


i Integer. A pointer toa ber_int_t should be supplied. The value stored will 
be in host byte order. The tag of the element must indicate the primitive form 
but is otherwise ignored during the decoding. The ber_scanf () function will 
return an error if the integer cannot be stored in aber int t. 


B Bitstring. A char ** argument should be supplied which will point to the 
allocated bits, followed by a ber len t * argument, which will point to the 
length (in bits) of the bit-string returned. The ldap_memfree() function 
must be called to free the bit-string. The tag of the element must indicate 
the primitive form (constructed bitstrings are not supported) but is otherwise 
ignored during the decoding. 


n Null. No argument is required. The element is simply skipped if it is 
recognized as a zero-length element. The tag is ignored. 


Vv Several octet strings. A char *** argument should be supplied, which upon 
return points to a allocated null-terminated array of char *’s containing the 
octet strings. NULL is stored if the sequence is empty. The ldap_memfree ( ) 
function must be called to free each element of the array and the array itself. 
The tag of the sequence and of the octet strings are ignored. 


V Several octet strings (which could contain null bytes). A struct berval *** 
should be supplied, which upon return points to a allocated null-terminated 
array of struct berval *’s containing the octet strings and their lengths. NULL 
is stored if the sequence is empty. The ber _bvecfree() function can be called 
to free the allocated memory. The tag of the sequence and of the octet strings 


are ignored. 

x Skip element. The next element is skipped. No argument is required. 
Begin sequence. No argument is required. The initial sequence tag and length 
are skipped. 

} End sequence. No argument is required. 

[ Begin set. No argument is required. The initial set tag and length are skipped. 


] End set. No argument is required. 


ber tag t ber peek tag (BerElement *ber, ber len t *lenPtr) ; 


The ber peek tag() function returns the tag of the next element to be parsed 
in the BerElement argument. The length of this element is stored in the *lenPtr 
argument. LBER_DEFAULT is returned if there is no further data to be read. 
The ber argument is not modified. 


ber tag t ber skip tag (BerElement *ber, ber len t *lenPtr) ; 


The ber skip _tag() function is similar to ber peek tag(), except that the state 
pointer in the BerElement argument is advanced past the first tag and length, 
and is pointed to the value part of the next element. This function should only be 
used with constructed types and situations when a BER encoding is used as the 
value of an OCTET STRING. The length of the value is stored in *lenPtr. 


ber tag t ber first element (BerElement *ber, 
ber len t *lenPtr, char **opaquePtr) ; 


ber tag t ber next element (BerElement *ber, 
ber len t *lenPtr, char *opaque) ; 
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The ber first _element() and ber next _element() functions are used to 
traverse a SET, SET OF, SEQUENCE or SEQUENCE OF data value. The 

ber first element () function calls ber skip _tag(), stores internal information 
in *lenPtr and *opaquePtr, and calls ber peek _tag() for the first element inside 
the constructed value. LBER_DEFAULT is returned if the constructed value is 
empty. The ber next element () function positions the state at the start of the 
next element in the constructed type LBER_DEFAULT is returned if there are 
no further values. 


The len and opaque values should not be used by applications other than as 
arguments to ber next element (), as shown in the following example: 


14.20.2.1 Decoding Example 
The following is an example of decoding an ASN.1 data type: 


Example2Request ::= SEQUENCE { 
dn OCTET STRING, -- must be printable 
scope ENUMERATED { b (0), s (1), w (2) }, 
ali ENUMERATED { n (0), s (1), £ (2), a (3) }, 
size INTEGER, 
time INTEGER, 
tonly BOOLEAN, 
attrs SEQUENCE OF OCTET STRING, -- must be printable 
[0] SEQUENCE OF SEQUENCE { 
type OCTET STRING -- must be printable, 
crit BOOLEAN DEFAULT FALSE, 
value OCTET STRING 
} OPTIONAL } 


#define TAG CONTROL LIST 0xA0U /* context specific cons 0 */ 


int decode _example2(struct berval *bv) 


BerElement *ber; 

ber len t len; 

ber tag_t res; 

ber int _t scope, ali, size, time, tonly; 
char *dn = NULL, **attrs = NULL; 

Int. 18e 0; 
ber = ber init (bv) ; 
if (ber == NULL) 


fputs ("ERROR ber init failed\n", stderr) ; 
return -1; 


} 


res = ber_scanf (ber,"{aiiiib{v}", &dn, &scope, éali, 
&size,&time, &tonly, &attrs) ; 


if (res == LBER_ERROR) { 

fputs ("ERROR ber_scanf failed\n", stderr) ; 
ber free (ber,1) ; 

return -1; 


/* *** use dn */ 
ldap_memfree (dn) ; 


for (1 = 0; attrs != NULL && attrs[i] != NULL; i++) { 
/* *** use attrs[i] */ 
ldap_memfree(attrs[il]); 


ldap_memfree (attrs) ; 


if (ber peek tag(ber,&len) == TAG CONTROL LIST) { 
char *opaque; 
ber _tag_t tag; 
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for (tag = ber first element (ber, &len, &opaque) ; 
tag != LBER DEFAULT; 
tag = ber next_element (ber, &len,opaque)) { 


ber _len_t tlen; 

ber tag _t ttag; 

char *type; 

ber int_t crit; 
struct berval *value; 


if (ber_scanf (ber,"{a",&type) == LBER ERROR) { 
fputs("ERROR cannot parse type\n", 
stderr) ; 
break; 


} 
/* *** use type */ 
ldap _memfree (type) ; 


ttag = ber peek tag(ber, &tlen) ; 
if (ttag == 0x01U) { /* boolean */ 
if (ber_scanf (ber,"b", 


&crit) == LBER ERROR) { 
fputs ("ERROR cannot parse crit\n", 
stderr) ; 
ree. =i 
break; 


} else if (ttag == 0x04U) { /* octet string */ 


crit = 0; 
} else { 
fputs ("ERROR extra field in controls\n", 
stderr ); 
break; 
} 
if (ber_scanf (ber,"0}",&value) == LBER ERROR) { 
fputs("ERROR cannot parse value\n", 
stderr) ; 
ress 
break; 


/* *** use value */ 
ber_bvfree (value) ; 


if ( rc == 0) { /* no errors so far */ 
if (ber_scanf(ber,"}") == LBER ERROR) { 
reo = =L; 


ber free(ber,1) ; 


return rc; 
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14.21 Using LDAP with HP SSL for OpenVMS 


Secure Sockets Layer (SSL) is the open standard security protocol for the secure 
transfer of sensitive information over the | nternet. 


You can establish HP SSL for OpenVMS Alpha on an LDAP session if the server 
supports such sessions. SSL uses X.509 public key technology to provide the 
following security functions: 
e |ntegrity and confidentiality of the LDAP dialog 
This is the most common use of HP SSL. The bytes sent over the wire are 
encrypted. 
e Authentication of the client 


Some servers use SSL to authenticate the client and make access control 
decisions based on the client identity. In this case, the dient must have 
access to its private key and its certificate. The client certificate subject is a 
DN. 


e Authentication of the server 


It might be important for the client to verify the identity of the server 
to which it is talking. In this case, the client must have access to the 
appropriate certification authority (CA) public keys. 


There are several versions of SSL: SSLv2 (2.0), SSLv3 (3.0), and TLSv1 (3.1). TLS 
is the latest Internet standard. It does not require the use of RSA algorithms. 
Usually the client specifies the highest version it supports, and the server 
negotiates downward, if necessary. The client library supports all the versions 
listed here. 


You can establish SSL over LDAP two different ways: 


e LDAPS 


This older, de facto standard uses a separate TCP/IP port (usually 636) 
specifically for SSL over LDAP. In this case, the second parameter to the 
ldap tls _start() function must be set to zero. 


e StartTLS 
This proposed Internet standard uses a regular LDAP port (usually 389) 
and requires the client to request the use of SSL. In this case, the second 
parameter to the ldap tls start() function must be set to 1. 

14.21.1 HP SSL Certificate Options 

The following session-handle options are specific to SSL and can be set by the 

ldap set _option() function: 

* LDAP_OPT_TLS CERT_REQUIRED (0x7001) void * 


Set to LDAP_OPT_ON if the client library requires a server certificate to be 
present the next time the ldap tls_start() function is called. The default 
value is LDAP_OPT_OFF; a server certificate is not required. 


* LDAP_OPT_TLS VERIFY_REQUIRED (0x7002) void * 


Set to LDAP_OPT_ON if the client library requires that a server certificate 
path be validated the next time the ldap tls start () function is called. The 
default value is LDAP_OPT_OFF; the server certificate, if any, is not verified. 


* LDAP_OPT_TLS_CERT_FILE (0x7003) char * 
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If L 


Set to the name of a file containing the client’s certificate for use by the 
ldap_tls_start() function. 


LDAP_OPT_TLS_PKEY_FILE (0x7004) char * 


Set to the name of a file containing the client's private key for use by the 
ldap_tls_start() function. 


LDAP_OPT_TLS CA FILE (0x7005) char * 

Set to the name of a file containing CA public keys used for validation of the 
server by the ldap tls _start() function. 

LDAP_OPT_TLS CA PATH (0x7006) char * 


Set to the name of a directory on disk containing CA public key files used for 
validation of the server by the ldap tls _start() function. 


LDAP_OPT_TLS_ VERSION (0x7007) int * 


Set to the desired SSL protocol version. This option takes one of the following 
values: 


1: TLSv1 only 
20: SSLv2 only 
23: SSLv2 or SSLv3 
30: SSLv3 only (default) 
31: TLSv1 only 


DAP_OPT_TLS VERIFY_REQUIRED is set to ON, either the LDAP_OPT_ 


TLS_CA_FILE or the LDAP_OPT_TLS_CA PATH option must be set. 


If d 


ient authentication is required, both LDAP_OPT_ TLS CERT _FILE and 


LDAP_OPT_TLS PKEY_FILE must be set. 


14.21.2 Obtaini 


ng a Key Pair 


In order for TLS to authenticate a client, the client must have a private key 
and a certificate. Obtain these from either a Certification Authority or a self- 
sign program. A self-sign program is included in the Open Source Security for 
OpenVMS product. 


14.22 Sample LDAP API Code 


The following is a sample of LDAP API code. 
#include <ldap.h> 


main () 


{ 


LDAP *1ld; 
LDAPMessage *res, *e; 
int 1, re; 
char *a, *dn; 
BerElement *ptr; 
char *kvals; 


/* open an LDAP session */ 
if ( (1d = ldap init( "dotted.host.name", ldap PORT )) == NULL ) 
exit( 1); 


/* authenticate as nobody */ 
if (( rc = ldap simple bind s( 1d, NULL, NULL )) != ldap SUCCESS ) { 
fprintf( stderr, "ldap simple bind_s: %s\n", 
ldap err2string( rc )); 
exit( 1); 
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/* search for entries with cn of "Babs Jensen", return all attrs */ 
if (( rc = ldap search_s( 1d, "“o=University of Michigan, c=US", 
ldap SCOPE SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) 
!= ldap SUCCESS ) { 
fprintf( stderr, "ldap search_s: %s\n", 
ldap err2string( rc )); 
exit( 1); 


/* step through each entry returned */ 

for ( e = ldap first _entry( 1d, res ); e != NULL; 
e = ldap _next_entry( 1d, e ) ) 

/* print its name */ 

dn = ldap get_dn( ld, e ); 

printf( "dn: %s\n", dn ); 

ldap memfree( dn ); 


/* print each attribute */ 
for ( a = ldap first_attribute( ld, e, &ptr ); a != NULL; 
a = ldap next _attribute( ld, e, ptr ) 

printf( "attribute: %s\n", a); 


/* print each value */ 

vals = ldap get_values( ld, e, a ); 

for ( i = 0; vals[i] != NULL; i++) { 
printf( "value: %s\n", vals[il] ); 


ldap value free( vals ); 
ldap memfree( a ); 


} 


if ( ptr != NULL ) { 
ber free( ptr, 0); 


} 
} 


/* free the search results */ 
ldap msgfree( res ); 


/* close and free connection resources */ 
ldap_unbind( ld ); 
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LOGINOUT (LGI) Routines 


The information in this chapter is intended for programmers implementing the 
requirements of site security administrators or third-party security software 
producers. 


This chapter differs from other parts of this book because it does not deal 
strictly with callable routines that are internal to the OpenVMS system. The 
LOGINOUT callout routines are designed by site security administrators. The 
callback routines are invoked by the callout routines. 


15.1 Introduction to LOGINOUT 


The OpenVMS login security program (LOGINOUT.EXE) supports calls to 
site-specific routines (_OGINOUT callout routines). These callout routines 
support custom login security programs such as smart card programs, pocket 
authenticator programs, and other alternative identification and authentication 
programs. The callout routines permit sites to combine portions of the 
LOGINOUT security policy functions with site login security functions to 
establish a customized login security environment. 


15.1.1 The LOGINOUT Process 
The site security administrator provides LOGINOUT with the following: 


e One or more shareable images comprised of modules that include callout 
routines 


¢ A list of the shareable images 


As login events occur, LOGINOUT invokes the applicable callout, thus enabling 
the site to replace or augment each event using site-specific modifications. 


The site may provide multiple callout images. The images are invoked in 
the order in which they are declared to the system. Each image contains an 
independently developed set of policy routines. 


Each callout routine may do one of the following: 

e Enforce site-specific policy functions 

¢ Defer to subsequent routines 

e Use elements of the standard OpenVMS policy functions 


Each callout routine may access LOGINOUT'’s internal state and callback 
routines using a vector of entry points. The callback routines allow the callout 
routines to communicate with the user and to incorporate elements of the 
standard OpenVMS policy functions in a modular fashion. 
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15.1.2 Using LOGINOUT with External Authentication 


The following sections describe LOGINOUT's interaction with the external 
authentication policy supported by OpenVMS. For more information about single 
sign-on and user authentication, see the HP OpenVMS Guide to Systen Security. 


Note 


The use of LOGINOUT callouts disables external authentication, making 
only the standard OpenVMS authentication policy available. 


Overview of External Authentication 

At sites using external authentication, all authentication decisions for users are 
actually made by the LAN manager rather than OpenVMS; however, OpenVMS 
account restrictions and quota checks remain in effect. 


To access the system, users must provide their LAN manager user 1D and 
password at the login prompt. If local password synchronization is required, 
one of the following messages is displayed indicating the outcome of the 
synchronization attempt: 


OpenVMS password has been synchronized with network password 

Not able to synchronize OpenVMS password with network password 

These messages can be suppressed on a per-user basis by setting the DISREPORT 
flag. 

Specifying Local Authentication 


The login command line supports the /LOCAL_PASSWORD qualifier. This 
qualifier indicates to LOGINOUT that the user intends to override external 
authentication by using their OpenVMS user name and password. This is 
considered a temporary means for logging in to the system when the external 
authentication service is unavailable. To use this qualifier, you must have 
SYSPRV privilege. 


When a user has logged in locally, the following message is displayed: 
Local logon successful; network logon service not used 


Locally authenticated users are not subject to OpenVMS password policy, 
since the system manager specified that these users are subject to external 
authentication policy only. 


15.1.3 The LOGINOUT Data Flow 


Figure 15-1 provides an overview of the data flow between LOGINOUT, the 
callout routines, and site-specific shareable images that can include one or more 
callout modules. 
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Figure 15-1 LOGINOUT Callout Routines Data Flow 
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15.2 LOGINOUT Callouts 


This section introduces the callouts that LOGINOUT uses to interface with the 
site-specific callout modules in the shareable images. The section also describes 
a set of callback routines that the callout routines can use to invoke services 
provided within LOGINOUT. 


15.2.1 LOGINOUT Callout Routines 


LOGINOUT calls a different site provided callout routine at each important 
step in its execution. Table 15-1 briefly describes the LOGINOUT callouts. See 
Section 15.4 for detailed descriptions of these routines. 


Table 15-1 LOGINOUT Callouts 


Callout Description 


LGI$ICR_AUTHENTICATE Authenticates the user account at login 


LGI$1CR_CHKRESTRICT Checks additional security restrictions 

LGI$ICR_DECWINIT Prepares for interactive contact with DE Cwindows users 

LGI$ICR_FINISH Gives site-specific code final control of the login process 

LGI$l1CR_IACT_START Prepares for interactive contact with users who are not 
using the DE Cwindows interface 

LGI$1CR_IDENTIFY Identifies the user at login 

LGI$ICR_INIT Initializes context variable 

LGI$ICR_J OBSTEP Indicates the start of each step in a batch job 

LGI$1CR_LOGOUT Prepares for logout 


15.2.2 LOGINOUT Callback Routines 


The callback routines enable the site's callout routines to communicate 
interactively with the user or to invoke other services provided by LOGINOUT. 
Table 15-2 briefly describes the LOGINOUT callback routines. See Section 15.5 
for detailed descriptions of these routines. 
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Table 15-2 LOGINOUT Callback Routines 


Routine 


Description 


LGI$ICB_ACCTEXPIRED 
LGI$1CB_AUTOLOGIN 
LGI$1CB_CHECK_PASS 


LGI$ICB_DISUSER 
LGI$ICB_GET_INPUT 
LGI$ICB_GET_SYSPWD 


LGI$1CB_MODALHOURS 
LGI$1CB_PASSWORD 
LGI$1CB_PWDEXPIRED 
LGI$1CB_USERPROMPT 
LGI$1CB_USERPARSE 


LGI$ICB_VALIDATE 


Checks for account expiration 
Verifies that standard rules for autologin apply 


Checks the entered password against the user 
authorization file (UAF) record 


Checks for DISUSER flag 
Enables interaction with the user 


Checks system password for character-cell interactive 
logins 
Checks for restrictions on access modes and access hours 


Generates prompts, reads input, and optionally 
validates input against system user authorization file 
(SY SUAF.DAT) 


Checks for password expiration 


Prompts for and reads input for character-cell interactive 
logins 

Parses input buffer data for character-cell interactive 
logins 

Validates the user name and password against the system 
user authorization file (SY SUAF.DAT) 


15.3 Using Callout Routines 


This section describes: 


e The calling environment 


¢ The callout routines and how they are organized and activated 


e The callout routines interface 


Section 15.3.5 contains a sample LOGINOUT program. 


15.3.1 Calling Environment 


The general form for invoking the callout routines is as follows: 


return-status = routine (standard_arguments_vector, context, routine_specific_args) 


The call elements include the following: 


e Standard argument vector: contains pointers to LOGINOUT data structures 
and callback routines for communicating with the user 


e Context: a longword that the site-specific program may use to store a pointer 


to local context 


e Routine-specific arguments: arguments directly related to the specific routine 


The callout routine’s return status must be one of the following: 
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Reiurn Siatus Interpretation 

SS$ NORMAL Access permitted; continue policy checks. Execute next policy 
image or OpenVMS policy function associated with this callout, 
if applicable. 


LGI$¢ SKIPRELATED Access permitted; discontinue checks. Continue with the login 
without further processing of login policy functions associated 
with this callout, including relevant OpenVMS policy functions 
built into LOGINOUT. 


Other Disallow the login: 


e Perform break-in detection and intrusion evasion, if 
appropriate. 


e Perform security audit. 


e Allow additional login attempts up to system-specified 
repeat limit, if appropriate. 


Note 


When a fatal error occurs, the policy module may terminate the login 

by signaling a severe error using the BLISS built-in SIGNAL_STOP or 
by calling LIB$SIGNAL. (See the HP OpMVMS RTL Library (LIB$) 
Manual for a description of the LIB$SIGNAL routine.) LOGINOUT will 
do a security audit, but it will not perform break-in detection or intrusion 
evasion. 


Avoid using a severe error termination unless the LOGINOUT process 
state is in jeopardy. LOGINOUT should terminate with a clean exit and a 
disallowed login whenever possible. 


15.3.2 Callout Organization 


A site may use several callout modules. For example, assume that the site is 
working with another program that uses logins or the site involves logins for 
various devices or logins at various security levels. 


LOGINOUT invokes the callout routines using a vector of entry points rather 
than the routine name. Each vector entry point corresponds to a policy function, 
and the first vector entry contains a count of the entry points in the vector, thus 
making the vector extendable. Figure 15-2 shows how a callout routine vector is 
organized. 
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Figure 15-2 Callout Organization 


Number of Entry Points 


Callout Routine 1 
Callout Routine 2 


Callout Routine n 
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Note that entry points may be accessed randomly. When a site-provided callout 
module does not provide a routine for a particular callout, the site must enter a 0 
value as a placeholder into the corresponding vector location. 


Callout modules may modify the vector during execution so that following events 
invoke different routines. For example, one of the initialization callout routines 
could modify the vector in anticipation of a following call to a different terminal 
or different job type, or it might zero the number of entry points to disable further 
calls to callout routines contained in the current callout module. 


15.3.3 Activating the Callout Routines 


A site activates the LOGINOUT callouts by identifying its callout images using 
the system executive-mode logical name LGI$LOGINOUT_CALLOUTS. The 
logical name may contain one value or a list of values that identify the callout 
images using either the: 


e File name of a module located in SYS$SHARE:*.E XE 

e Name of an executivemode system logical name representing a full file 
specification 

Note 


LOGINOUT is installed with privileges. Therefore, any image containing 
LOGINOUT callout routines must be installed. 


If the identifying logical is a list of several images, the images are sequentially 
activated in the listed order. If a specified image is not activated, the login fails. 


To protect against intrusion, the site uses the system parameter LGI_CALLOUTS 
to specify the number of callout images. If this value is nonzero and the supplied 
number of callout images does not correspond to the value, the login fails. 


Sites that want to control their job creation process and authenticate each 
network login by implementing LOGINOUT callouts must set the NET _ 
CALLOUTS system parameter to 255. This ensures that LOGINOUT is called for 
every network login — bypassing any existing server processes. 


The default value of NET _CALLOUTS (0) could bypass the LOGINOUT callouts 
and allow NET$ACP to perform its own proxy and login authentication. See the 
file SYS$SYSTEM:NETSERVER.COM for an example of how NET$ACP performs 
its own authentication and management of server processes. 
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Parameter values 1 to 254 are reserved by HP for future use. 


Note 


Callouts are not invoked when LOGINOUT initiates the STARTUP 
process during system bootstrap. 


For the logical name LGI$LOGINOUT_CALLOUTS, a clusterwide logical 
name cannot be used. The number of names in the system logical name 
LGI$LOGINOUT_CALLOUTS must always match the value of the system 
parameter LGI_CALLOUTS. LGI$LOGINOUT_CALLOUTS must bein 
the regular system logical name table and not in a clusterwide logical 
name table. 


When applications that support LGI_CALLOUTS are starting and 
stopping, they manipulate LGI$LOGINOUT_CALLOUTS as well as 
LGI_CALLOUTS. A clusterwide logical name would be incorrect since not 
all nodes in a cluster would have the same LGI_CALLOUTS at the same 
time. Nodes where the values did not match would experience login and 
logout failures. 


15.3.4 Callout Interface 


Each image containing LOGINOUT callouts must define a universal symbol 
LGI$LOGINOUT_CALLOUTS. This symbol represents a vector of |ongwords 


that points to the entry points for the various callout routines, as shown in the 
following illustration: 
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The vector is headed by a longword count that delimits the number of callout 


routines supported by the callout module. Unused vector entries are identified by 
a 0 value. 


Each callout routine has access to a vector of LOGINOUT internal variables, 
including the addresses of callback routines and other useful information. The 
vector entries are defined as offsets from the beginning of the vector. The vector 
has the following format: 
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Callback 
Routines 


LGI$ICB_GET_INPUT 
LGI$ICB_DECW_IDENT 
LGI$ICB_DECW_AUTH 
LGI$ICB_GET_SYSPWD 
LGI$ICB_USERPROMPT 
LGI$ICB_USERPARSE 
LGI$ICB_AUTOLOGIN 
LGI$ICB_PASSWORD 
LGI$ICB_CHECK_PASS 
LGI$ICB_VALIDATE 
LGI$ICB_ACCTEXPIRED 
LGI$ICB_PWDEXPIRED 


LGI$ICB_DISUSER 


LGI$ICB_MODALHOURS 


LGI$A_ICR_CREPRC_FLAGS 
LGI$A_ICR_JOB_TYPE 
LGI$A_ICR_SUBPROCESS 
LGI$A_ICR_TERMINAL_DEV 
LGI$A_ICR_TT_PHYDEVNAM 
LGI$A_ICR_TT_ACCPORNAM 
LGI$A_ICR_CLINAME 
LGI$A_ICR_CLITABLES 
LGI$A_ICR_NCB 


LGI$A_ICR_LOGLINK 
Internal 


LGI$A_ICR_REM_NODE_NAM Variables 


LGI$A_ICR_REM_ID 
LGI$A_ICR_UAF_RECORD 
LGI$A_ICR_INPUT_RAB 
LGI$A_ICR_AUTOLOGIN 
LGI$A_ICR_USERNAME 
LGI$A_ICR_PWD1 
LGI$A_ICR_PWD2 


LGI$A_ICR_PWDCOUNT 


LGI$A_ICR_NETFLAGS 
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Symbols of the form LGI$ICB_x are the addresses of the callback routines that 
the callout routines use to communicate with the user (See Table 15-2). Other 
offsets are addresses of useful variable information internal to LOGINOUT. These 
are described in Table 15-3. 


Table 15-3 Useful LOGINOUT Internal Variables 


Symbols 


Definition 


LGI$A_ICR_CREPRC_FLAGS 
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on the major job types of PRC$V_BATCH, PRC$V_ 
NETWRK, PRC$V_INTER, and other values such 
as PRC$V_NOPASSWORD (used for interactive 
jobs created on logged-in terminals). 
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Table 15-3 (Cont.) Useful LOGINOUT Internal Variables 


Symbols 


Definition 


LGI$A_ICR_] OB_TYPE 


LGI$A_ICR_SUBPROCESS 


LGI$A_ICR_TERMINAL_DEV 
LGI$A_ICR_TT_PHYDEVNAM 


LGI$A_ICR_TT_ACCPORNAM 


LGI$A_ICR_CLINAME 


LGI$A_ICR_CLITABLES 


LGI$A_ICR_NCB 


LGI$A_ICR_LOGLINK 


LGI$A_ICR_REM_NODE_NAM 


LGI$A_ICR_REM_ID 


LGI$A_ICR_UAF_RECORD 


The job type from the J 1B (byte). LOGINOUT does 
the following: 


e Retrieves the job type with a GET] PI during 
initialization. 


e Modifies it during execution. (Its value may 
change between the LGI$ICR_INIT and later 
callouts.) 


e Writes it back into the J 1B before exiting. 


For interactive jobs, this flag indicates J |B$C_ 
LOCAL, J |B$C_REMOTE, or J |B$C_DIALUP. 


The subprocess flag (byte) indicates whether a 
subprocess is being logged in. 


The terminal device flag (byte). 


A descriptor containing the terminal’s physical 
device name (null if input is not from a terminal). 


A descriptor containing the terminal’s access port 
name (null if input is not from a terminal or is 
from a terminal without an associated access port). 


A descriptor containing the command language 
interpreter (CLI) name, parsed from the user name 
qualifiers. Valid only for interactive jobs. 


A descriptor containing the CLI tables, parsed from 
the user name qualifiers. Valid only for interactive 
jobs. 


A descriptor containing the network control block. 
Valid only for network jobs. 


A longword containing the local link number. Valid 
only for network jobs and when doing a SET HOST 
command from a DECnet-Plus remote terminal. 


A descriptor containing the remote node name or 

a printable representation of its node number if 
the name is not available. Valid only for network 
jobs and when doing a SET HOST command from a 
DECnet-Plus remote terminal. 


A descriptor containing the remote ID. This may 
be the user ID on the remote system if the source 
operating system sends the user name. Otherwise, 
it is as defined for the source system. Valid only 
for network jobs and when doing a SET HOST 
command from a DECnet-Plus remote terminal. 


Address of the LOGINOUT internal variable 
containing the address of the user authorization 
file (UAF) record. 


Note that because the record will be written back to 
the UAF record, callout routines must not modify 
the contents of the UAF record. 


(continued on next page) 
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Table 15-3 (Cont.) Useful LOGINOUT Internal Variables 


Symbols 


Definition 


LGI$A_ICR_INPUT_RAB 
LGI$A_ICR_AUTOLOGIN 


LGI$A_ICR_USERNAME 
LGI$A_ICR_PWD1 
LGI$A_ICR_PWD2 
LGI$A_ICR_PWDCOUNT 


LGI$A_ICR_NETFLAGS 


A RAB (record access block) that may be used to 
communicate with an interactive user. 


A flag (byte) indicating whether an autologin is 
being used for this interactive job. 

A descriptor for handling the user name. 

A descriptor for handling the primary password. 
A descriptor for handling the secondary password. 
A longword containing the count of passwords 


expected for this user. Valid only for interactive 
jobs. 
A flag (word) containing authorization information. 


Valid only for network jobs. The bits that have 
been defined are: 


e NET_PROXY: A proxy request. 


e NET _PREAUTH: DECnet-Plus has 
preauthorized the login. 


e NET _DEFAULT_USER: The session or object 
database has a default user and no password 
checking is required. 


e NET _PROXY_OK: The requested proxy has 
been allowed by either LOGINOUT or the 
site-provided callout routines. 


15.3.5 Sample Program 


The following C program illustrates the use of LOGINOUT callouts. The sample 
program changes the user name and password prompts to “Who are you?” and 
“Prove it.” The program also adds the message “Goodbye.” at logout. 


#module LGISCALLOUT EXAMPLE "TOY LOGINOUT callout example" 
/* 


** 6 FACILITY: 


¥ System help 


** This program can be compiled with the following command 


bat $ CC/STANDARD=VAXC/LIST/PREFIX LIBRARY ENTRIES=ALL LGISCALLOUT_EXAMPLE.C 


** This program can be linked with the following example command procedure 


bss $ LINK/SHARE=LGISCALLOUT EXAMPLE SYSSINPUT/OPT 


at LGISCALLOUT_ EXAMPLE. OBJ 
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bali SYMBOL VECTOR=(LGISLOGINOUT_CALLOUTS=DATA) 


kk 


** The following steps are used to install the program: 
kK 


iad $ DEFINE/SYSTEM/EXEC LGISLOGINOUT_CALLOUTS LGISCALLOUT_ EXAMPLE 


kk 


** Tf the program is not located in SYSSSHARE, define it as follows: 
kK 


il $ DEFINE/SYSTEM/EXEC LGI$CALLOUT EXAMPLE filespec 


kK 
** [Remember that, without SYSNAM privilege, the /EXEC qualifier is ignored.] 
kk 

**  § INSTALL ADD LGI$CALLOUT EXAMPLE 

**  § RUN SYSSSYSTEM: SYSGEN 

**  SYSGEN> USE ACTIVE 

**  SYSGEN> SET LGI_CALLOUTS 1 

**  SYSGEN> WRITE ACTIVE 

kK 

** The value of LGI_CALLOUTS is the number of separate callout images 

** (of which this example is one) that are to be invoked. If there is 

** more than one image, the logical LGISLOGINOUT_CALLOUTS must have a 

** list of equivalence names, one for each separate callout image. 

kK 

+} 

/* 

kk 

** INCLUDE FILES 

kK 

al 

#include descrip 

#include rms 

#include stsdef 

#include ssdef 
#include prcdef 


/* Declare structures for the callout vector and the callout arguments vector */ 


struct LGI$CALLOUT VECTOR { 
long int LGI$L_ICR ENTRY COUNT; 
int (*LGISICR_INIT) (); 
*LGI$ICR_IACT START) 
*LGI$ICR_DECWINIT) () 
*LGIS$ICR IDENTIFY) () 
*LGI$ICR_ AUTHENTICATE 
*LGI$ICR_CHKRESTRICT) 
*LGIS$ICR FINISH) (); 
* 
k 


(); 
) 0; 
(); 


LGISICR LOGOUT) () ; 
LGISICR JOBSTEP) (); 


struct LGISARG VECTOR { 


int (*LGISICB GET INPUT) (); 
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*reservedl1) (); 
*reserved2) (); 
(*LGISICB_ GET SYSPWD (); 
*LGISICB_ USERPROMPT (); 
*LGISICB_ USERPARSE) 
*LGISICB AUTOLOGIN) 
*LGISICB PASSWORD) ; 
*LGISICB CHECK PASS) (); 
int *LGISICB | VALIDATE) 7 
void (*LGISICB ACCTEXPIRED 
void (*LGISICB PWDEXPIRED (); 
int *LGISICB | DISUSER) (); 
void (*LGISICB MODALHOURS) (); 
short *LGISA_ ICR_CREPRC_FLAGS; 
char *LGISA_ ICR. JOB. TYPE; 
char *LGISA_ ICR.  SUBPROCESS ; 
char *LGISA_ICR_ TERMINAL DEV; 

truct dsc$descriptor_s *LGISA ICR_TT PHYDEVNAM; 
truct dscS$descriptor_s *LGISA_ICR_TT ACCPORNAM; 
truct dscSdescriptor_s *LGISA_ICR_CLINAME; 
truct dscSdescriptor_s *LGISA ICR _CLITABLES; 
truct dscS$descriptor_s *LGISA_ICR_NCB; 

*LGISA ICR _LOGLINK; 
truct dscSdescriptor_s *LGISA ICR R 
truct dscSdescriptor s *LGISA_ ICR | R 
nsigned char *LGISA ICR_UAF | RECORD; 
truct RAB *LGISA_ ICR_ INPUT | RAB; 

Ag *LGISA_ ICR _ AUTOLOGIN; 
truct dscSdescriptor_s *LGISA ICR USERNAME; 
truct dsc$descriptor_s *LGISA ICR _PWD1; 
truct dsc$descriptor_s *LGISA ICR PWD2; 

int *LGISA_ ICR PWDCOUNT; 
short int *LGISA_ ICR_NETFLAGS ; 


i 


globalvalue int LGI$ SKIPRELATED, /* callout’s return status */ 
LGI$ DISUSER, 

LGIS_ INVPWD, 

LGIS | NOSUCHUSER, 

LGIS | “NOTVALID, 

LGI$ INVINPUT, 

LGI$ CMDINPUT, 

LGI$ FILEACC; 


< 
Oo 

to ct ct ct ct ct b- ct ct 
Qa 


=) 
ct 


EM NODE NAM; 
EM I 


| ID; 


EE 
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static int callout_logout () ; 
static int callout_decwinit() ; 
static int callout_identify() ; 
static int callout authenticate () ; 


globaldef struct LGISCALLOUT VECTOR LGISLOGINOUT_CALLOUTS = 


{ 
9, 
0, /* init */ 
0, /* iact_start */ 
callout decwinit, /* decwinit */ 
callout identify, /* identify */ 
callout authenticate, /* authenticate */ 
0, /* chkrestrict */ 
0, /* finish */ 
callout _logout, /* logout */ 
0, /* jobstep */ 
he 

/* DECwindows initialization */ 
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static int callout_decwinit () 


/* Disable any further calls */ 
LGISLOGINOUT_CALLOUTS.LGI$L_ICR_ENTRY COUNT =" 0 
/* Return and do standard DECwindows processing */ 
return (SS$ NORMAL) ; 


} 
/* Identification */ 


static int callout_identify(struct LGISARG VECTOR *arg_vector) 


int status; 
SDESCRIPTOR (wru,"\r\nWho are you? "); 


/* This example deals only with interactive jobs */ 
if (1 (Farg_ vector- >LGISA_ ICR_CREPRC_FLAGS & PRCSM_ INTER) ) 
return(SS$ NORMAL); /* Not interactive, do normal processing */ 
if (*arg_ vector- >LGISA_ ICR CREPRC FLAGS & PRCSM | NOPASSWORD) 
return(SS$ NORMAL); /* Invoked as logged in, don’t prompt */ 
if (*arg_vector->LGISA_ICR_SUBPROCESS != 0) 
return(SS$ NORMAL); /* Don’t prompt on subprocesses */ 


/* Check for autologin */ 


(SVMS_STATUS SUCCESS (arg _vector->LGISICB AUTOLOGIN() ) ) 
return (LGI$ SKIPRELATED) ; /* Yes, it’s an autologin */ 


(!SVMS_ STATUS SUCCESS (status = arg_vector->LGI$ICB USERPROMPT (&wru) ) ) 
return (status); /* On error, return error status */ 


/* Successful prompt and parse; skip OpenVMS policy */ 
return (LGI$ SKIPRELATED) ; 


/* Buthentication */ 


static int callout_authenticate(struct LGISARG VECTOR *arg vector) 


int status; 
SDESCRIPTOR (proveit,"\r\nProve it: "); 


/* This example deals only with interactive jobs */ 

if (!(*arg_vector->LGISA_ ICR_CREPRC_FLAGS & PRCSM_INTER) ) 

return(SS$ NORMAL); /* Not interactive, do normal processing */ 
if (*arg_ vector->LGISA_ICR_CREPRC_FLAGS & PRCSM NOPASSWORD) 

return (SS$ NORMAL); /* Invoked as logged in, don’t prompt */ 

if *arg_vector->LGI$A_ ICR SUBPROCESS != 0) 

return (SS$ NORMAL) ; /* Don't prompt on subprocesses */ 


if (*arg_ vector->LGISA_ICR_PWDCOUNT != 0) 
- pre account has at least one password */ 
(!SVMS_STATUS SUCCESS (status = 
arg_vector->LGI$ICB_ PASSWORD (0, &proveit) ) ) 
return (status); /* On error, return error status */ 


if (*arg_vector->LGISA_ICR_PWDCOUNT == 2) 
/* This account has two passwords */ 
(!$VMS_STATUS SUCCESS (status = 
arg_vector->LGISICB PASSWORD (1, &proveit) ) ) 
return (status); /* On error, return error status */ 


/* Successful prompt and password validation; skip OpenVMS policy */ 
return (LGI$ SKIPRELATED) ; 


/* LOGOUT command */ 
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static int callout_logout (username, procname, creprc flags, write fao) 
struct dsc$descriptor_s *username, *procname; 
short *creprc_flags; 
void (*write fao) (); 


char *Goodbye = "| Goodbye."; /* This will become an ASCIC */ 
if ((int) write fao != 0) /* If output is permitted... */ 
Goodbye [0] =strlen (Goodbye) -1; /* Fill in ASCIC count */ 
write fao (Goodbye) ; /* and write it */ 


return (SS$ NORMAL) ; 


} 
15.4 LOGINOUT Callout Routines 


The following sections describe the individual callout routines. Each description 
includes the following: 


e The format of the call command 

e The anticipated information returned by the called routine 
e« The arguments presented to the called routine 

e A general description of the routine 

e Typical condition values that indicate the return status 


e« Associated OpenVMS policy function, that is, the standard LOGINOUT policy 
functions developed for OpenVMS compared with the site-provided policy 
functions 


The Typical Condition Values and the Associated OpenVMS Policy Function 
headings are unique to the LOGINOUT callout routines. 
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LGI$ICR_AUTHENTICATE—Authenticate the Password 


Format 


Returns 


Arguments 


Description 


The LGI$1CR_AUTHENTICATE callout routine authenticates passwords. 


LGI$SICR_AUTHENTICATE arg_vector ,context 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Returns status indicating whether and how to proceed with the login. 


arg_vector 

OpenVMS usage: vector 

type: vector_longword_unsigned 
access: modify 

mechanism: by reference 


Vector containing callbacks and login information. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Pointer to site's local context. 


All logins involving a password invoke the LGI$1CR_AUTHENTICATE callout 
routine. The routine is not called for subprocesses, network jobs invoked by proxy 
logins, or logged-in DECterm sessions. 


The following pointers are used in password authentication: 


e Longword LGI$A_ICR_PWDCOUNT points to a location that contains 
the number of OpenVMS passwords for a particular account. Nonexistent 
accounts are assigned a password count of 1 to avoid revealing them by the 
absence of a password prompt. 


e For DECwindows logins only, longword LGI$A_ICR_PWD1 points toa 
location that contains the user’s primary password. 


e For DECwindows logins only, longword LGI$A_ICR_PWD2 points toa 
location that contains the user’s secondary password, if applicable. 
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For all logins except DE Cwindows logins, the LGI$I1CR_AUTHENTICATE callout 
routine may use the following callback routine sequence: 


e« Call LGI$1CB_ PASSWORD for standard password prompting with an 
optional nonstandard prompt and the option of checking or just returning the 
password or other information obtained. 


e Call LGI$l1CB_GET_INPUT for completely customized prompting for each 
required piece of authentication information. 


For DECwindows logins, neither the LGI $I1CB_PASSWORD callback routine nor 
the LGI$I1CB_GET_INPUT callback routine needs to be called. The user enters 
the password using the DE Cwindows login dialog box before LOGINOUT issues 
the LGI$1CR_-AUTHENTICATE callout. 


For a complete description of the DE Cwindows flow of control, see the description 
of the LGI$1|CR_DECWINIT callout routine. 


All logins involving a password may invoke the LGI$ICB_VALIDATE callback 
routine. This routine validates against SYSUAF.DAT passwords obtained by 
customized prompting using descriptors for the user name and passwords. 
Optionally, the login may call the LGI$ |CB_CHECK_PASS callback routine to 
validate passwords. 

For interactive jobs, the LGI$I1CR_-AUTHENTICATE routine should check the 
DISUSER flag using the LGI$I1CB_DISUSER callback routine to preserve the 
consistency of the “invalid user” behavior for disabled accounts. For other types 
of jobs, use the LGI$1CR_CHKRESTRICT callout routine to check the DISUSER 
flag. 


Note 


LOGINOUT checks the DISUSER flag as part of the authentication 
process because, if it is checked later, an intruder could determine that 
the correct user name and password had been entered and that the 
account is disabled. This is ddiberatdy hidden by keeping the user in the 
retry loop for a disabled account. 


If the DISUSER flag is checked with other access restrictions in the 
authorization portion, this causes an immediate exit from LOGINOUT. 


Break-in detection, intrusion evasion, and security auditing are done in the case 
of any failure return from LGI$1CR_-AUTHENTICATE. 


If this routine returns LGI$ SKIPRELATED, the user is fully authenticated, 
and no further authentication is done by either the site or OpenVMS. If 

this routine returns an error for an interactive job, the system retries the 
identification and authentication portions of LOGINOUT. For character-cell 
terminals, this consists of calling the LGI$ICR_IDENTIFY and LGI$ICR_ 
AUTHENTICATE callout routines; for DE Cwindows terminals, this consists of 
calling the LGI$|CR_DECWINIT routine. The number of retries is specified by 
the SYSGEN parameter LGI_RETRY_LIM. 
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SS$ NORMAL 
LGI$ SKIPRELATED 


Other 


Associated OpenVMS Policy Function 
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LGI$ICR_AUTHENTICATE 


Access permitted; continue policy checks. 


Access permitted; omit calls to the LGI$ICR_ 
AUTHENTICATE callout routine in subsequent 
images and calls to the associated OpenVMS 
policy function. 


Disallow the login; perform break-in detection, 
intrusion evasion, and security auditing. For 
interactive logins, retry identification and 
authentication portions of LOGINOUT, up to 
the number specified in the SYSGEN parameter 
LGI_RETRY_LIM. 


Perform standard password prompting and validation. 
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LGI$SICR_CHKRESTRICT—Check Access Restrictions 


The LGI$1CR_CHKRESTRICT callout routine may be used to check site-specific 
access restrictions that are not usually included in the OpenVMS login. 


Format 
LGI$SICR_CHKRESTRICT  arg_vector ,context 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Returns status indicating whether and how to proceed with the login. 
Arguments 
arg_vector 
OpenVMS usage: vector 
type: vector_longword_unsigned 
access: modify 
mechanism: by reference 
Vector containing callbacks and login information. 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Pointer to site's local context. 
Description 


All logins call this 


routine after the password is authenticated to allow the site 
to check other access restrictions. The site may check its own access restrictions 


and any of the following OpenVMS access restrictions: 


Access Restriction 


Callback Routine Used to Check Restriction 


Account expiration 


LGI$ICB_ACCTEXPIRED 


Password expiration LGI$ICB_PWDEXPIRED 


Account disabled 


LGI$ICB_DISUSER 


Access modes and times LGI$I1CB_MODALHOURS 
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Typical Condition Values 


SS$ NORMAL Access permitted; continue policy checks, 
including all of the normal OpenVMS policy 
functions associated with the callback routines 
used to check restrictions. 

LGI$ SKIPRELATED Access permitted; omit calls to the LGI$ICR_ 
CHKRESTRICT callout routine in subsequent 
images and calls to the associated OpenVMS 
policy functions. 


Other Disallow the login. 


Associated OpenVMS Policy Functions 


Check password expiration, check DISUSER flag, check account expiration, and 
check restrictions on access time. 
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LGISICR_DECWINIT—DECwindows Initialization 


The LGI$1CR_DECWINIT callout routine enables site-specific initialization 
functions for logins from the DE Cwindows session manager. 


Format 
LGI$ICR_DECWINIT  arg_vector ,context 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Returns status indicating whether and how to proceed with the login. 
Arguments 
arg_vector 
OpenVMS usage: vector 
type: vector_longword_unsigned 
access: modify 
mechanism: by reference 
Vector containing site-specified callbacks and login information. 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Pointer to site's local context. 
Description 


LOGINOUT invokes the LGI$l1CR_DECWINIT callout routine at the start of a 
DECwindows session login. This callout routine does not support a return status 
of LGI$ SKIPRELATED. Returning LGI$ SKIPRELATED for this callout causes 
unpredictable results. Use the LGI$ICR_DECWINIT callout routine only to 
prepare other callout routines for a DE Cwindows login. 


After issuing the LGI$1CR_DECWINIT callout, LOGINOUT performs the 
following tasks: 


¢ Creates the DECwindows login dialog box and reads the user name and 
password entered by the user 


* Calls the LGI$l1CR_IDENTIFY callout 


e Obtains the user authorization file (UAF) record 


If the UAF record specifies two passwords, the DE Cwindows login dialog 
box is amended to prompt for the second password, and the listed tasks are 
repeated. 


e Issues the LGI$ICR_AUTHENTICATE callout 
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e If the LGI$ICR_AUTHENTICATE callout routine did not return LGI$_ 
SKIPRELATED, validates the passwords against the UAF record 


The LGI$ICR_IDENTIFY and LGI$ICR_-AUTHENTICATE callouts may create 
additional DE Cwindows dialog boxes to communicate with the user, but the 
initial dialog box must be created by LOGINOUT. 


Typical Condition Values 


SS$ NORMAL Access permitted; continue policy checks. 

LGI$ SKIPRELATED Not supported. Returning this status will cause 
unpredictable behavior. 

Other Disallow the login. 


Associated OpenVMS Policy Function 


Create dialog box, read user name and password, and call the identification and 
authentication routines. 
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LGI$ICR_FINISH—Final Site Action 


The LGI$ICR_FINISH callout routine permits the site program to take final local 
action before exiting from LOGINOUT. 


Format 

LGI$ICR_FINISH arg_vector ,context ,user_cond_value 
Returns 

OpenVMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Returns status indicating whether and how to proceed with the login. 
Arguments 

arg_vector 

OpenVMS usage: vector 

type: vector_longword_unsigned 

access: modify 

mechanism: by reference 

Vector containing callbacks and login information. 

context 

OpenVMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Pointer to site’s local context. 

user_cond_value 

OpenVMS usage: cond_value 

type: longword_unsigned 

access: read only 

mechanism: by value 

SS$ NORMAL for successful login; otherwise, reason for failure. 
Description 


The site program calls this routine immediately before exiting to take any final 
local actions relative to the login process. There is no OpenVMS login security 
policy associated with LGI$ICR_FINISH. 


LGI$ICR_FINISH does not affect login completions because the login is audited 
before the routine is invoked. The routine has no effect on error recovery when a 
login fails, and it cannot cause a successful login to fail. 
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Typical site action may include the following: 
¢ Override job quotas 


e Stack CLI command procedures by examining and modifying the logicals 
PROC1 through PROC9 


Caution 


For DECwindows session manager logins, be careful modifying the 
command procedure stack to avoid adversely affecting the command file 
that invokes the session manager. 


e Other postlogin processing 
Typical Condition Values 


LGI$ SKIPRELATED Access permitted; omit calls to the LGI$ICR_ 
FINISH callout routine in subsequent images. 


Associated OpenVMS Policy Function 


None. 
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LGI$ICR_IACT_START—Character-Cell Initialization 


The LGI$lCR_IACT_START callout routine may perform initialization functions 
for logins from interactive character-cell terminals. 


Format 
LGI$ICR_IACT_START  arg_vector ,context 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Returns status indicating whether and how to proceed with the login. 
Arguments 
arg_vector 
OpenVMS usage: vector 
type: vector_longword_unsigned 
access: modify 
mechanism: by reference 
Vector containing callbacks and login information. 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Pointer to site's local context. 
Description 


This routine makes the first contact for all interactive logins from other than 
DECwindows terminals after opening the input and output files but before any 
other dialogue with the user. 


At this point, the site should be preparing to augment or replace the OpenVMS 
system password routine. The callback routine LGI$ICB_GET_SYSPWD provides 
access to the system password routine. However, because LGI$|CB_GET_ 
SYSPWD returns only on success, the site design should consider what action to 
take in case LGI$|CB_GET_SYSPWD does not return control to LGI$I1CR_IACT_ 
START. 


The LGI$ICR_IACT_START routine can use the LGI$I1CB_GET_INPUT callback 
routine to: 


¢ Get input from the user 


e Use an OpenVMS RMS record access block (RAB) to establish appropriate 
terminal mode settings 
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Typical Condition Values 


SS$ NORMAL Access permitted; continue OpenVMS system 
password routine. 
LGI$ SKIPRELATED Access permitted; omit calls to the LGI$ICR_ 


IACT_START callout routine in subsequent 
images and calls to the associated OpenVMS 
policy function. 


Other Exit quietly to preserve the illusion of an inactive 
line. 
Associated OpenVMS Policy Function 


Get the system password. 
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LGI$ICR_IDENTIFY—ldentify the User 


The LGI$ICR_IDENTIFY callout routine identifies the user from the user name 


input. 
Format 
LGI$ICR_IDENTIFY arg_vector ,context 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Returns status indicating whether and how to proceed with the login. 
Arguments 
arg_vector 
OpenVMS usage: vector 
type: vector_longword_unsigned 
access: modify 
mechanism: by reference 
Vector containing callbacks and useful login information. 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
Pointer to site's local context. 
Description 


The LGI$ICR_IDENTIFY callout routine is invoked for all types of login 
procedures. If the site uses the standard OpenVMS DE Cwindows dialogue, 
the identification routine may be called more than once for accounts with two 
passwords. 


If you plan to replace the standard OpenVMS identification processing, consider 
the following: 


¢ For logins from character-cell terminals, obtain the user name using one of 
the following: 


— A dialogue with the user. The site can access OpenVMS user name 
processing to obtain the standard prompt or a specialized prompt by 
invoking the LGI$ICB_USERPROMPT callback routine Alternatively, 
the site may invoke the LGI$ICB_GET_INPUT callback routine to 
communicate with the user. 


— Site-specific equipment, for example, a card reader or some other 
authentication device. 
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— Autologins. The site may do the identification portion of the standard 
OpenVMS autologin by invoking the LGI$ICB_AUTOLOGIN callback 
routine. 

e For logins from the DE Cwindows Session Manager, LOGINOUT invokes the 
callout module's LGI$ICR_IDENTIFY callout routine after obtaining the user 
name and putting it in LGI$A_ICR_USERNAME. The LGI$ICR_IDENTIFY 
callout routine can provide any additional checking of the user name that 
may be required. 

¢ For batch jobs, network jobs, logged-in DECterm sessions, and subprocesses, 
the site may use the LGI$ICR_IDENTIFY routine to verify information 
without a user dialogue. 


Calls to LGI$ICR_IDENTIFY are always followed by validation of the presence of 
the user name in the system authorization file, unless the routine is invoked for a 
subprocess. 


Typical Condition Values 


SS$ NORMAL Access permitted; continue policy checks. 


LGI$ SKIPRELATED Access permitted; omit calls to the LGI$ICR_ 
IDENTIFY callout routine in subsequent images 
and calls to the associated OpenVMS policy 
function. 


Other Disallow the login. 


Associated OpenVMS Policy Function 


Perform standard OpenVMS user name prompting and parsing. 
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LGI$ICR_INIT—Initialization Callout Routine 


The LGI$ICR_INIT callout routine may perform any required initialization 


functions. 


Format 


LGI$ICR_INIT arg_vector ,context 


Returns 


OpenVMS usage: cond_value 


type: 
access: 
mechanism: 


longword (unsigned) 
write only 
by value 


Returns status indicating whether and how to proceed with the login. 


Arguments 


arg_vector 


OpenVMS usage: vector 


type: 
access: 
mechanism: 


vector_longword_unsigned 
modify 
by reference 


Vector containing callbacks and login information. 


context 


OpenVMS usage: context 


type: 
access: 
mechanism: 


longword (unsigned) 
modify 
by reference 


Pointer to site's local context. 


Description 


This routine is called for all job types before opening input and output files. 
If desired, the callout routine may initialize the context argument, which 
LOGINOUT subsequently passes to each callout routine with the address of local 


storage specific to the callout image. 


Typical Condition Values 


SS$ NORMAL 


LGI$ SKIPRELATED 


Other 
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Access permitted; continue policy checks. 


Access permitted; omit calls to the LGI $IlCR_ 
INIT callout routine in subsequent images. 


Disallow the login. 
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Associated OpenVMS Policy Function 


None. 
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LGI$ICR_JOBSTEP—Batch Job Step 


The LGI$ICR_J OBSTEP callout routine signals the start of each batch job step. 


Format 

LGI$ICR_JOBSTEP _input_file_name ,context ,write_fao 
Returns 

OpenVMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Not applicable. 
Arguments 

input_file_name 

OpenVMS usage: descriptor 

type: character string 

access: read 

mechanism: by reference 

The name of the input file. 

context 

OpenVMS usage: context 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

Pointer to site’s local context. 

write_fao (fao_string[,arg1[,arg2][,...]]]) 

OpenVMS usage: routine 

type: procedure 

access: read 

mechanism: by reference 

Address of a routine that may be called to format and display output. The 

routine has fao_string as its first argument, followed by a variable number of 

arguments. (See the $FAO system directive in the HP OpenVMS System Services 

Reference Manual for more information.) 
Description 


The LGI$ICR_J OBSTEP routine alerts the site of each job step in a batch job. 
The routine is invoked as LOGINOUT processes each job step. For the first job 
step, the LGI$ICR_J OBSTEP callout routine is invoked immediately following 
the LGI$I1CR_IDENTIFY callout routine. For all other job steps, it is the only 
callout routine that is invoked. 
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The routine is provided with the input file name, but the input file is not open 
when the routine is called. For the first job step, the LGI$ICR_INIT callout 


routine may provide the batch job step routine with context. For other job steps, 
the context argument is a null. 


For all job steps except the first, the output file is open, and the routine specified 
by the write_fao argument is available. 


There is no OpenVMS policy associated with LGI$ICR_J OBSTEP. 
Typical Condition Values 


LGI$ SKIPRELATED or any’ Access permitted; omit calls to the LGI$ICR_ 
error value J OBSTEP callout routine in subsequent images. 


Associated OpenVMS Policy Function 


None. 
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LGI$ICR_LOGOUT—Installation Logout 


The LGI$ICR_LOGOUT callout routine permits the site callout images to respond 
to the DCL command LOGOUT. 


Note 


This routine is not called if the calling process is deleted with 
STOP/PROCESS ($DELPRC). If the calling terminal is disconnected 
when logout occurs, this routine must not produce output. 


Format 

LGI$ICR_LOGOUT username ,processname ,creprc_flags ,write_fao 
Returns 

OpenVMS usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

Returns logout status from the site program. 
Arguments 

username 

OpenVMS usage: descriptor 

type: character string 

access: read 

mechanism: by reference 

User name. 

processname 

OpenVMS usage: descriptor 

type: character string 

access: read 

mechanism: by reference 


Process name. 


creprc_flags 
OpenVMS usage: mask_longword 


type: longword_unsigned 
access: read 
mechanism: by reference 


Process creation status flags. 
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write_fao (fao_string[,arg1[,arg2][,..-]]]) 
OpenVMS usage: routine 


type: procedure 
access: read 
mechanism: by reference 


Procedure for writing data. The value is 0 if output is not permitted. 


Address of a routine that may be called to format and display output. The 
routine has fao_string as its first argument, followed by a variable number of 
arguments. (See the $FAO system directive in the HP Op@MVMS Systen Services 
Reference Manual for more information.) 

Description 


The LGI$ICR_LOGOUT routine is invoked after auditing is completed and 
immediately before LOGOUT prints the logout message. This routine cannot 
prevent the logout from finishing, but it may prevent display of the standard 
logout message. 

Typical Condition Values 


LGI$ SKIPRELATED or any Access permitted; omit calls to the LGI$ICR_ 
error value LOGOUT callout routine in subsequent images. 


Associated OpenVMS Policy Function 


None. 
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15.5 LOGINOUT Callback Routines 


LOGINOUT callout routines use callback routines to interact with the user or to 
access other LOGINOUT services. This section describes the individual callback 
routines. The description of each routine includes the following: 


The format of the call command 

The anticipated information returned by the called routine 
The arguments presented to the called routine 

A general description of the routine 


Condition values that indicate the return status of the routine, success or 
failure 
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LGI$ICB_ACCTEXPIRED—Account Expiration 


The LGI$l1CB_ACCTEXPIRED callback routine checks for account expiration. 


Format 
LGI$ICB_ACCTEXPIRED 


Returns 


No value. Does not return on failure. 


Arguments 


None. 


Description 


The site can use this callback routine to determine if the specified account is 
expired. If the account is expired, the LGI$1CB_ ACCTEXPIRED callback routine: 


e Writes its standard error message to the user terminal, if a terminal exists 
e Does not return control to the caller 


Condition Values Returned 


None. 
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LGI$ICB_AUTOLOGIN—Check for Autologin 


Format 


Returns 


Arguments 


Description 


The site may use the LGI$I|CB_AUTOLOGIN callback routine to determine 
whether the standard OpenVMS autologin functionality applies for this terminal. 


LGI$ICB_AUTOLOGIN 


OpenVMS usage: value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


True (logical 1) if autologin enabled; O otherwise. 


None. 


If the standard OpenVMS autologin functionality applies, the callback routine 
returns the user name to the site program using the standard argument vector so 
that the autologin process may continue. 


The autologin determination is made before the site prompts for the user 
passwords. The callback routine is applicable only for interactive character-cell 
logins. 


Note 


Standard OpenVMS policy uses autologin only on directly connected 
or LAT connected character-cell terminals. The LGI$ICB_ 
AUTOLOGIN callback routine checks the automatic login file (ALF) 
SY S$SYSTEM:SYSALF.DAT to make the determination. 


A DECwindows callout can include a method for doing a DE Cwindows 
autologin. In that case, the callout routine should set the autologin flag to 
true before returning control to LOGINOUT. 


Condition Values Returned 


None. 
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LGI$ICB_CHECK_PASS—Check Password 


Format 


Returns 


Arguments 


Description 


The LGI$l1CB_CHECK_PASS callback routine checks a password against the user 
authorization file (UAF) record. 


LGI$ICB_CHECK_PASS password ,uaf_record ,owd_number 


OpenVMS usage: value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


The value 1 for a valid password. The value -4 for an invalid password. 


password 

OpenVMS usage: character string 
type: string descriptor 
access: read only 
mechanism: by reference 


User-supplied password to be validated. 


uaf_record 

OpenVMS usage: buffer 

type: vector_byte (unsigned) 
access: read only 

mechanism: by reference 


Address of buffer containing UAF record. 


pwd_number 
OpenVMS usage: value 


type: longword (unsigned) 
access: read only 
mechanism: by value 


Password number, 0 (primary) or 1 (secondary). 


The site uses this callback routine to check the user-supplied password against 
the UAF record provided as the second argument. If the password is valid, the 
routine returns a 1 in RO; if the password is invalid, the routine returns a -4 in 
RO. 


Condition Values Returned 


None. 
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LGI$ICB_DISUSER—Check for Disabled User Account 


The LGI$lCB_DISUSER callback routine checks the disabled user account flag. 


Format 
LGI$ICB_DISUSER action 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Condition value in RO. 
Argument 
action 
OpenVMS usage: value 
type: longword (unsigned) 
access: read only 
mechanism: by value 
This argument can take two values: 
If Value of Action Is... Then... 
LGI$ DISUSER_STOP Do not return on error. 
LGI$ DISUSER_RETURN Return LGI$ DISUSER or SS$ NORMAL. 
Description 


The site can use this callback routine to establish the standard OpenVMS action 
if the DISUSER flag is set. 


Condition Values Returned 


LGI$ DISUSER 
SS$ NORMAL 
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LGI$ICB_GET_INPUT—Get User Input 


Format 


Returns 


Arguments 


Description 


The LGI$l1CB_GET_INPUT callback routine enables interaction with the user. 


LGI$ICB_GET_INPUT rab ,flags 


No value. Does not return on failure. 


rab 

OpenVMS usage: rab 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Data structure used to set up a read-with-prompt OpenVMS RMS operation. 
Normally you pass the RAB address in LGI$A_ICR_INPUT_RAB. 


flags 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


A data structure that determines the error response as follows: 


Flags 

Value Response 

0 Normal error message. 

1 LOGINOUT exits quietly. 

2 Normal error message; however, the callback routine returns control to 


the caller rather than exiting on timeout (timeout status is in RAB). 


The LGI$1CB_GET_INPUT callback routine invokes the LOGINOUT input 
routine to enable interaction with character-cell terminal users. The read 
operation provides a timeout to ensure that the UAF record does not remain 
locked if the user presses Ctrl/S. 


Condition Values Returned 


No return value. Examine status in RAB to determine the results of the read 
operation. 
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LGI$SICB_GET_SYSPWD—Get System Password 
The LGI$l|CB_GET_SYSPWD callback routine validates the system password. 


Format 
LGISICB_GET_SYSPWD 


Returns 
No value. Does not return on failure. 


Arguments 


None. 


Description 


This callback routine performs standard system password-checking for interactive 
logins on character-cell terminals only. 


If the system password is validated, this callback routine returns control to the 
caller. If the system password is not validated, the LOGINOUT image exits, and 
the login is terminated. 


Condition Values Returned 


None. 
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LGI$SICB_. MODALHOURS—Perform Access Checks 


The LGI$1CB_MODALHOURS callback routine checks for restrictions on access 
modes and access hours. 


Format 
LGI$ICB_. MODALHOURS 


Returns 


No value. Does not return on failure. 


Arguments 


None. 


Description 


The site uses this callback routine to establish the access modes and access hours 
available to the user. If the user is not authorized to access the system from this 
login class (batch, dialup, local, remote, network) at this time (as specified in the 
UAF), the callback routine: 


e Writes its standard error message to the user terminal, if there is a terminal 
e Does not return control to the caller 


Condition Values Returned 


None. 
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LGI$ICB_PASSWORD—Produce Password Prompt 


Format 


Returns 


Arguments 


The LGI$1CB_PASSWORD callback routine produces the specified password 
prompt and then processes the input. 


LGI$ICB_PASSWORD  password_number ,prompt ,buffer 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Condition value in RO. 


password_number 
OpenVMS usage: value 


type: longword (unsigned) 
access: read only 
mechanism: by value 


A numeric value indicating which password to prompt for and what action to take 
on it: 


Value Prompt for 


0 Primary password and validate it 

1 Secondary password and validate it 

-1 Primary password but do not validate it 
-2 Secondary password but do not validate it 


-3 Arbitrary 32-character value returned to buffer specified in buffer 


If the value is -3, you must specify the prompt argument and the buffer 
argument. 


prompt 

OpenVMS usage: character string 
type: string descriptor 
access: read only 
mechanism: by reference 


String that must begin with “cr,lf”. If this argument is not supplied, the standard 
prompt is used. 
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buffer 

OpenVMS usage: character string 
type: string descriptor 
access: modify 
mechanism: by reference 


Buffer having at least 32 bytes available to store password when password_ 
number argument value is -3. 


Description 


The site can use this callback routine to interactively prompt for passwords. 
The routine uses either the standard OpenVMS password prompt or a prompt 
provided by the caller in the second argument. 


The password is returned in one of the following locations, depending on the 
value of the password_number argument: 


Value of Password_Number Argument Location 

Oor-1 LGI$A_ICR_PWD1 

lor -2 LGI$A_ICR_PWD2 

-3 buffer argument 
Note 


This routine will do overstriking, if necessary, to support echo local 
terminals. See the HP OpenVMS Programming Concepts Manual for 
more information about echo terminals. 


Condition Values Returned 


SS$ NORMAL Success. 
LGI$¢_INVPWD Password check failed. 
LGI$ NOSUCHUSER No UAF record found. 
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LGI$ICB_PWDEXPIRED—Password Expiration 


The LGI$l1CB_PWDEXPIRED callback routine checks for password expiration. 


Format 
LGI$ICB_PWDEXPIRED 


Returns 


No value. Does not return on failure. 


Arguments 


None. 


Description 


Use this callback routine to determine whether the account password has expired. 
If the password is expired, the callback routine: 


e Writes its standard error message to the user terminal, if there is a terminal 


e Does not return control to the caller 


Condition Values Returned 


None. 
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LGISICB_USERPARSE—Parse Username 


Format 


Returns 


Argument 


Description 


The LGI$l1CB_USERPARSE callback routine parses the user name input. 


LGI$ICB_USERPARSE _ input_buffer 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Condition value in RO. 


input_buffer 
OpenVMS usage: character string 


type: string descriptor 
access: read only 
mechanism: by reference 


The input buffer must contain the characters LOGIN in the first five character 
locations, followed by an ASCII space character and then the user name and 
applicable site-specified qualifiers. 


The site can use this callback routine to parse input for interactive logins on 
character-cell and DE Cwindows terminals. 


Upon completion of this routine, the user name is accessible at the LGI $A __ 
USERNAME entry in the standard arguments vector. 


Condition Values Returned 


True (1) if successful; otherwise, any condition code returned by CLI$PARSE. 
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LGI$ICB_USERPROMPT—Prompt for Username 


Format 


Returns 


Argument 


Description 


The LGI$l1CB_USERPROMPT callback routine prompts for the user name. 


LGI$ICB_USERPROMPT prompt 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Condition value in RO. 


prompt 

OpenVMS usage: character string 
type: string descriptor 
access: read only 
mechanism: by reference 


A string that must begin with “cr,If”. For example, to produce the standard user 
name prompt, use your language equivalent of the following BLISS value: 


UPLIT(12,UPLIT BYTE(CR,LF,’Username: ')) 
Declare the string in C using the following statement: 
SDESCRIPTOR(<variable name>, "lrlnUsername:") 
You then pass the descriptor using the variable name. 


This routine also produces the standard user name prompt if you pass the value 
0 for this argument. 


Use this callback routine to interactively prompt for the user name on a 
character-cell terminal. The callback routine reads the response to the prompt 
and does standard DCL parsing for the user name and any qualifiers provided. 
Upon completion of this routine, the user name is accessible at the LGI $A __ 
USERNAME entry in the standard arguments vector. 


Condition Values Returned 


SS$ NORMAL Success. 
LGI$ NOTVALID Retry count exceeded for user input. 
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LGI$ICB_VALIDATE—Validate User Name and Passwords 


The LGI$ICB_VALIDATE callback routine validates the user name and 
passwords against the system authorization file. 


Format 
LGI$ICB_VALIDATE username ,pwd1 ,pwd2 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Condition value in RO. 
Arguments 
username 
OpenVMS usage: character string 
type: string descriptor 
access: read only 
mechanism: by reference 
User name. 
pwd1 
OpenVMS usage: character string 
type: string descriptor 
access: read only 
mechanism: by reference 
Primary password. 
pwd2 
OpenVMS usage: character string 
type: string descriptor 
access: read only 
mechanism: by reference 
Secondary password. 
Description 


The site can use this callback routine to validate the user name and the 
user's primary and secondary passwords against the system authorization 
file (SYSUAF.DAT). The routine also: 


e Updates the user authorization (UAF) record with information about login 
failures 


e Performs security auditing 


e Performs break-in detection and intrusion evasion 
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Condition Values Returned 


Success, or an error indicating the reason for the failure. 
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Mail Utility (MAIL) Routines 


The callable interface of the Mail utility (MAIL) lets you send messages to users 
on your system or on any other computer connected to your system with DE Cnet. 
This chapter describes how application programs using callable MAIL routines 
can perform the following functions: 


e Create and access mail files 
e Access and manipulate a message or group of messages 
e« Create and send messages to a user or group of users 
e Access and manipulate the user profile database 
For information about the DCL interface to the Mail utility, see the OpenVMS 
User’s Manual. 
16.1 Messages 


Messages are files that contain information you want to send to other users. 
Messages having one or two blocks are part of a mail file, while messages having 
more than two blocks are external sequential files. 


External files reside in the same directory as the mail file that points to them. 


Structure of a Message 


A message consists of header information and the bodypart. The message 
bodypart consists of text records that contain information you want to send to 
another user. 


Figure 16-1 illustrates the format of a mail message. 


Figure 16-1 Standard Message Format 


From: MYNODE::USER "The Celestial Navigator" 1) 
To: NODE: :J_DOE 

ler USER (3) 

Sub}: Perseids ... 4) 


(continued on next page) 
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Figure 16-1 (Cont.) Standard Message Format 


Get ready. Tuesday of this week (August 12th), one 6 
of the most abundant meteor showers of the year will occur. 
The Perseids, also known as the St. Laurence’s Tears, stream 
across earth’s orbit at 319.3 degrees. Radiant 3h4m +58 degrees. 
Fine for photography with an average magnitude of 2.27. 
There will be some fireballs, fainter white or yellow 
meteors, and brighter green or orange or red ones. About one 
third of the meteors, including all the brightest, leave 
yellowish trains, which may be spectacular, up to 2 
degrees wide and lasting up to 100 seconds. Brighter 
meteors often end in flares or bursts. 
The parts of a message are as follows: 
e Header information 
@ From: field specifies the sender and an optional personal name string 
@ To: fied specifies the direct addressee 
© CC: field specifies the carbon copy addressee 
@ Subj: field specifies the topic of the message 
¢ Bodypart 
© First line of the bodypart 
@ Last line of the bodypart 


External Message Identification Number 
In addition, the file name of an external message uses the following format: 


MAILSnnnnnnnnnnnnnnnn. MAI 


wheren ...n is the external message identification number. 


16.2 Folders 


The Mail utility organizes messages by date and time received and, secondarily, 
by folder name. All messages are associated with a folder name—either default 
folders or user-specified folders. The Mail utility associates mail messages with 
one of three default mail folder names. Table 16-1 describes the three default 
mail folders. 


Table 16-1 Default Mail Folders 


Folder Contents 

NEWMAIL Newly received, unread messages 

MAIL Messages that have been read and not deleted 
WASTEBASKET Messages designated for deletion 


You can also place messages in any user-defined mail folder and file. 
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16.3 Mail Files 


16.4 User 


A mail file is an indexed file that contains the following types of data: 
e¢ Header information for all messages 

e Text of short messages 

¢ Pointers to long messages 


In addition, you can select messages from mail files as well as copy or move 
messages to or from mail files. 


Mail File Format 

The indexed mail file format offers two advantages: use of folders and faster 
access time than sequential access. Indexed mail files use two keys to locate 
messages—a primary key denoting the date and time received and a secondary 
key using the folder name. 


Profile Database 


The Mail utility maintains an indexed data file VMSMAIL_PROFILE.DATA 
that serves as a systemwide database of user profile entries. A user profile 
entry is a record that contains data describing a Mail user’s default processing 
characteristics and whose primary key is the user name. Table 16-2 summarizes 
information contained in a user profile entry. 


Table 16—2 User Profile Information 


Field Function 
Directory Default MAIL subdirectory 
Form Default print form 
Forwarding address Forwarding address 
Personal name string User-specified character string included in the message 
header 
Queue name Default print queue name 
Flags 
Automatic purge Purging of the wastebasket folder on exiting 
CC: prompt Carbon copy prompt 
Copy self forward Copy to self when forwarding a message 
Copy self reply Copy to self when replying to a message 
Copy self send Copy to self when sending a message 
Signature file Text file that is automatically appended to the end of 


the body of a mail message 


Both the callable interface and the user interface access the user profile database 
to determine default processing characteristics. 


16.5 Mail Utility Processing Contexts 


The Mail utility defines four discrete levels of processing, or contexts for 
manipulating mail files, messages, folders, and the user profile database as 
shown in Table 16-3. 
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Table 16-3 Levels of Mail Utility Processing 


Context Entity 

Mail file Mail files and folders 

Message Mail files, folders, and messages 
Send Messages 

User User profile database 


Within each context, your application processes specific entities in certain ways 
using callable MAIL routines as described in the sections that follow. 


Initiating a MAIL Context 


You must explicitly begin and end each MAIL context. Each group of routines 
contains a pair of context-initiating and terminating routines. 


When you begin processing in any context, the Mail utility performs the following 
functions: 


1. Allocates sufficient virtual memory to manage context information 
2. Initializes context variables and internal structures 


Terminating a MAIL Context 

Terminating a MAIL processing context deallocates virtual memory. You must 
explicitly terminate processing in any context by calling a context-terminating 
routine. 


16.5.1 Callable Mail Utility Routines 


There are four types of callable Mail utility routines, each corresponding to the 
context within which they execute. A prefix identifies each functional group: 


*  MAIL$MAILFILE_ 
*  MAIL$MESSAGE_ 
* MAIL$SEND_ 
* MAIL$USER_ 


Table 16-4 lists Mail utility routines according to context. 


Table 16-4 Callable Mail Utility Routines 
Context Routine 


Mail file MAIL$MAILFILE_BEGIN 
MAIL$MAILFILE_CLOSE 
MAIL$MAILFILE_COMPRESS 
MAIL$MAILFILE_END 
MAIL$MAILFILE_INFO_FILE 
MAIL$MAILFILE_MODIFY 
MAIL$MAILFILE_OPEN 
MAIL$MAILFILE_PURGE_WASTE 


(continued on next page) 


MAIL-—4 Mail Utility (MAIL) Routines 


Mail Utility (MAIL) Routines 
16.5 Mail Utility Processing Contexts 


Table 16-4 (Cont.) Callable Mail Utility Routines 


Context Routine 


Message MAIL$MESSAGE_BEGIN 
MAIL$MESSAGE_COPY 
MAIL$MESSAGE_DELETE 
MAIL$MESSAGE_END 
MAIL$MESSAGE_GET 
MAIL$MESSAGE_INFO 
MAIL$MESSAGE_MODIFY 
MAIL$MESSAGE_SELECT 


Send MAIL$SEND_ABORT 
MAIL$SEND_ADD_ADDRESS 
MAIL$SEND_ADD_ATTRIBUTE 
MAIL$SEND_ADD_BODYPART 
MAIL$SEND_BEGIN 
MAIL$SEND_END 
MAIL$SEND_MESSAGE 


User MAIL$USER_BEGIN 
MAIL$USER_DELETE_INFO 
MAIL$USER_END 
MAIL$USER_GET_INFO 
MAIL$USER_SET_INFO 


16.5.2 Single and Multiple Threads 


Once you have successfully initiated MAIL processing in a context, you have 
created a thread. A thread is a series of calls to MAIL routines that uses the 
same context information. Applications can contain one or more threads. 


Single Threads 

For example, consider an application that begins mail file processing; opens, 
compresses, and closes a mail file; and ends mail file context processing. This 
application executes a single thread of procedures that reference the same context 
variable names and pass the same context information. 


Multiple Threads 

You can create up to 31 concurrent threads. Applications that contain more than 
one thread must maintain unique context variables for each thread in order to 
pass thread-specific context information. 


The Mail utility returns the condition value MAIL$ NOMORECTX when your 
process attempts to exceed the maximum number of allowable threads. 


16.6 Programming Considerations 


The calling sequence for all MAIL routines consists of a status variable, an entry 
point name, and an argument list. All arguments within the argument list are 
required. All callable MAIL routines use the same arguments in their calling 
sequences as described in the following example: 


STATUS=MAILSMAILFILE BEGIN(CONTEXT, IN ITEM LIST, OUT _ITEM LIST) 


The variable status receives the condition value, and the argument context 
receives the context information. The arguments in_item_list and out_item_list 
are input and output item lists that contain one or more input or output item 
descriptors. 
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16.6.1 Condition Handling 


At run time, a hardware- or software-related event can occur that determines 
whether or not the application executes successfully. The Mail utility processes 
such an event, or condition in the following ways: 


e Signals the condition value 
e Returns the error code 


You can establish your own condition handler or allow the program to signal the 
default condition handler. 


Returning Condition Values 
You can disable signaling for any call by specifying the item code MAIL$_ 


NOSIGNAL as an item in the input item list. 
16.6.2 Item Lists and Item Descriptors 


Your application passes data to callable MAIL routines and receives data from 
routines through data structures called item lists defined in your program. 


16.6.2.1 Structure of an Item Descriptor 


An input or output item list is a data structure that consists of one or more input 
or output item descriptors. 


The following table summarizes the characteristics of item lists: 


Item Descriptor Characteristics 

Input Each descriptor points to a buffer or file from which Mail reads 
data. 

Output Each descriptor points to a buffer or file to which Mail writes 
data. 


An item descriptor is a data structure consisting of three longwords as described 
in Figure 16-2. 


Figure 16-2 Item Descriptor 


ZK-1705-GE 
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Item descriptor fields are described as follows: 


Field Function 
Item code Specifies an action the routine is to perform. 
Buffer length Specifies the length in bytes of an input or output 

buffer. 
Buffer address Specifies the address of the input or output buffer. 
Return length address Depends on the type of item code specified: 

Item 

Code Use 

Input Not used; specify 0. 

Output Address of a longword that receives 

the length of the result. 
Noite 


You can specify item descriptors in any order within an item list. 


Item Codes 
The item code defines an action that the routine is to perform. Input and output 
item codes are specified in input and output item descriptors, respectively. 


Boolean input and output item codes request an operation but do not pass data to 
the called routine. For example, the item code MAIL$ USER_SET_CC_PROMPT 
sets the CC prompt flag enabling use of CC: field text. 


For a complete list of input and output item codes, see Tables 16-10 and 16-11. 


16.6.2.2 Null Item Lists 
Both the input and output item list arguments in the MAIL routine calling 
sequence are required. However, there might be situations when you do not want 
to request an operation or no input or output item codes are listed for the routine. 
In such cases, you must pass the value 0 in the function call. 


16.6.2.3 Declaring Item Lists and Item Descriptors 
Depending on the programming language you are using, refer to the appropriate 
language reference manual for more information about declaring data structures 
and creating variables. 


16.6.2.4 Terminating an Item List 
Terminate an item list with a null item descriptor. Assign the value 0 to each 
field in the item descriptor. 


16.6.3 Action Routines 


Certain callable MAIL routines allow you to specify an action routine. An 
action routine transfers control to a user-written subroutine that performs 
specific tasks. 
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The mail file, message, and send contexts permit the use of action routines for 
specific reasons. Table 16-5 summarizes the types of action routines and the 
contexts in which they are used. 


Table 16-5 Types of Action Routines 


Context Routine Action Routine 

Mail file MAIL$MAILFILE_INFO FILE Provides information about 
folder and mail files. 

Message MAIL$MESSAGE_COPY Copies messages between 
files and folders. 

Send MAIL$SEND_MESSAGE Success and error results; 


sends a text file to an 
existing address list. 


The preceding table summarizes typical uses of action routines. However, an 
action routine can perform any task you specify. See the Guide to Creating 
OpenVMS Modular Procedures for more information about action routines. 
Mail File and Folder Action Routine Calling Sequence 


The main portion of the application calls the action routine and passes values to 
it using parameters. The calling sequence of a mail file or folder action routine is 
as follows: 


entry-point-name(userdata,foldername) 


The argument userdata is the address of a required longword that contains 
user-specified data, and the argument foldername is the address of a descriptor 
of the foldername. 

Send Action Routine Calling Sequence 

The calling sequence of a send action routine is as follows: 


entry-point-name(username,signal-array,userdata) 


The argument username is the address of a descriptor of the user name to 
which the application successfully sent a message; signal-array is the address 
of a signal array containing the success message; userdata is the address of an 
optional longword that contains user-specified data. 


16.7 Managing Mail Files 


Using mail files involves opening and closing both default mail files and user- 
created mail files, displaying folder names, and purging and compressing mail 
files. Table 16-6 summarizes each mail file routine and its function. 


Table 16-6 Mail File Routines 


Routine Description 
MAIL$MAILFILE_BEGIN Initiates mail file processing 
MAIL$MAILFILE_CLOSE Closes a mail file 
MAIL$MAILFILE_COMPRESS Compresses a mail file 


(continued on next page) 
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Table 16-6 (Cont.) Mail File Routines 


Routine Description 

MAIL$MAILFILE_END Terminates mail file processing 

MAIL$MAILFILE_INFO_FILE Obtains information about the mail file 

MAIL$MAILFILE_MODIFY Changes the wastebasket folder name and the 
default mail file name 

MAIL$MAILFILE_OPEN Opens a mail file 

MAIL$MAILFILE_PURGE_WASTE Purges a mail file 


Mail file context processing involves accessing and manipulating one or more mail 
files. 

Initiating the Mail File Context 

Your application must call MAIL$MAILFILE_ BEGIN to perform mail file context 
processing. 


When you call MAIL$MAILFILE_ BEGIN successfully and begin processing in the 
mail file context, you have created a thread. You must specify the same context 
variable name in routine calls within the same thread. 

Terminating the Mail File Context 

Terminate processing in the mail file context calling MAIL routines in the 
following order: 


1. Terminate message context processing (if applicable) using MAIL$MESSAGE _ 
END. 


2. Close the currently open mail file using MAIL$MAILFILE CLOSE. 
3. Terminate mail file context processing using MAIL$MAILFILE_END. 


The following sections describe these actions in more detail. 


16.7.1 Opening and Closing Mail Files 


Before you perform any activities on existing messages, folders, and mail files, 
you must first open a mail file. Whenever you open a mail file, you must do so 
explicitly using MAIL$MAILFILE_ OPEN. You can open only one mail file per 

mail file thread. 


Note that each routine references the same context variable. An open mail file 
must be explicitly closed with a call toMAIL$MAILFILE CLOSE. 


16.7.1.1 Using the Default Specification for Mail Files 


To open a mail file, Mail must first locate it using either a default or a user- 
specified mail file specification. A mail file specification consists of the following 
components: disk and directory, file name, and file type. 
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If you use the default file specification, the Mail utility locates and opens the 
default mail file using the following information: 


Component Source 

User’s disk and directory Retrieved from the user authorization file (UAF) 
MAIL subdirectory Retrieved from the user profile entry 

Mail file name and type MAIL.MAI 


16.7.1.2 Specifying an Alternate Mail File Specification 
You can use the default specification for mail files or specify all or part of an 
alternate mail file specification. 
When to Specify an Alternate Mail File Specification 


The following mail file routines accept alternate mail file specifications when you 
use the item codes MAIL$ MAILFILE_DEFAULT_NAME or MAIL$ MAILFILE_ 
NAME or both: 


e MAIL$MAILFILE_COMPRESS 
e MAIL$MAILFILE_INFO_FILE 
¢ MAIL$MAILFILE_MODIFY 

e MAIL$MAILFILE_OPEN 


How the Mail Utility Creates an Alternate Mail File Specification 


The Mail utility constructs an alternate mail file specification by using program- 
supplied mail file specifications to modify the default specification for mail files in 
the following order of importance: 


1. Program-supplied file specification (MAIL$ MAILFILE NAME) 
¢ Program-supplied disk and directory 
¢ Program-supplied file name and type 


2. Program-supplied default file specification (MAIL$ MAILFILE_DEFAULT_ 
NAME) 


¢ Program-supplied disk and directory 
¢ Program-supplied file name and type 
3. Default specification 


If you are using MAIL$ MAILFILE_DEFAULT_ NAME and you specify 0 as the 
buffer size and address, the Mail utility uses the current device and directory. 


The default specification for mail files applies unless overridden by your program- 
supplied mail file specifications. Mail file specifications defined with MAIL$_ 
MAILFILE_NAME override those defined with MAIL$ MAILFILE_DEFAULT_ 
NAME. 


For example, an application can override the default specification 
$DISKO:[USER]JMAIL.MAIL by defining an alternate device type $DISK99: 
using MAIL$ MAILFILE_NAME. The result is $DISK99:[USER]JMAIL.MAI. The 
application can further modify the specification by defining a different mail file 
MYMAILFILE.MAI using MAIL$ MAILFILE_DEFAULT_NAME. The new mail 
file specification is $DISK99:[USER]MYMAILFILE.MAI. 
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16.7.2 Displaying Folder Names 


As the size of your mail files increases with messages and folders, you might 
want to display your folder names. A user-written folder action routine lets you 
do this. 


In the mail file context, MAIL$¢MAILFILE_INFO_FILE can be used to invoke 

a folder action routine that displays folder names in a mail file. If you specify 
the item code MAIL$ MAILFILE_FOLDER_ ROUTINE, MAIL$MAILFILE_INFO 
passes a descriptor of a folder name to the action routine repeatedly until it 
encounters no more folder names and passes a null descriptor. 


16.7.3 Purging Mail Files Using the Wastebasket Folder 


The Mail utility associates messages designated for deletion with a wastebasket 
folder. Purging mail files of messages in the wastebasket folder that are 
designated for deletion is one way to conserve disk space. You can also use 

the Mail utility to conserve disk space by reclaiming disk space and compressing 
mail files, as described in the sections that follow. 


Note that purging the wastebasket folder removes the messages from the 
wastebasket folder but might not reclaim disk space. 


16.7.3.1 Reclaiming Disk Space 
Simply deleting the messages does not mean you will automatically reclaim the 
disk space. The Mail utility uses a system-defined threshold of bytes designated 
for deletion to determine when to reclaim disk space. When the total number of 
total bytes designated for deletion exceeds the threshold, the Mail utility performs 
a reclaim operation. 


You can override the deleted bytes threshold and request a reclaim operation 
using MAIL$MAILFILE_PURGE_WASTE with the input item code MAIL$_ 
MAILFILE_ RECLAIM. 


16.7.3.2 Compressing Mail Files 


Compressing mail files is a way of conserving disk space. Mail file compression 
provides faster access to the folders and messages within the mail file. When 
you call MAIL$MAILFILE_COMPRESS, Mail removes unused space within the 
specified mail file. 


16.8 Message Context 


Message context processing involves manipulating existing messages as well as 
creating and deleting folders and mail files. Table 16-7 summarizes routines 
used in the message context. 


Table 16-7 Message Routines 


Routine Description 
MAIL$MESSAGE_BEGIN Initiates message processing 
MAIL$MESSAGE_COPY Copies messages 
MAIL$MESSAGE_DELETE Deletes messages 
MAIL$MESSAGE_END Terminates message processing 


(continued on next page) 
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Table 16-7 (Cont.) Message Routines 


Routine Description 

MAIL$MESSAGE_GET Retrieves a message 

MAIL$MESSAGE_INFO Obtains information about a specified message 

MAIL$MESSAGE_ MODIFY Identifies a message as replied, new, or marked 

MAIL$MESSAGE_ SELECT Selects a message or messages from the currently open 
mail file 


Initiating the Message Context 


Message context processing can begin only after a mail file has been opened. Your 
application must explicitly call MAIL$MESSAGE_ BEGIN in order to execute 
message context processing. 


The Mail utility passes mail file context information to the message context when 
you call MAIL$¢MESSAGE_BEGIN with the input item code MAIL$ MESSAGE _ 
FILE CTX. 

Terminating the Message Context 


To terminate message-level processing for a specific thread, you must call 
MAIL$MESSAGE_END to deallocate memory. 


16.8.1 Selecting Messages 


Applications select messages using MAIL$MESSAGE SELECT to copy and move 
messages between folders as well as to read, modify, or delete messages. You 
must select messages before you can use them. You must specify a folder name 
when you select messages. 


You can select messages based on the following criteria: matching character 
strings, message arrival date and time, and message characteristics. 
Matching Character Strings 


You can select a message or set of messages from a mail file by specifying one or 
more character substrings that you want to match with a character substring in 
the header information of a message or group of messages. You must specify the 
specific bodypart in the message header where the substring is located. 


e From: line 
e To: line 

« CC: line 

¢ Subject: line 


The Mail utility searches the specified folder for message headers that contain 
the matching character substring. This method of selection is useful when you 
want to select and use messages from or to a particular user that are associated 
with many folder names. 


When you specify more than one character substring, the Mail utility performs a 
logical AND operation to find the messages that contain the correct substring. 
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Message Arrival Date and Time 


You can also select a message or group of messages based on their arrival time 
that is, when you received them. Applications select messages according to two 
criteria as follows: 


e« Messages received before a specified date or time or both 
e« Messages received on or after a specified date or time or both 


The Mail utility searches the mail file and selects messages whose primary key 
(date and time) matches the date and time specified in your application. 
Message Characteristics 


You can select messages based on Mail system flag values that indicate the 
following message characteristics: 


e New 
e Marked 
e Replied 


For example, you can select unread messages in order to display them or to 
display a message you have marked. 


16.8.2 Reading and Printing Messages 


After a message is selected, an application iteratively retrieves the contents 
of the bodypart record by record. The message can be retrieved using 
MAIL$MESSAGE_GET and can then be stored in a buffer or file. 


Displaying a Message 

To display a message on the terminal screen, you should store the message in a 
buffer and use the host programming language command that directs data to the 
screen. 

Printing a Message 


To print a message on a print queue on your system, you should write the 
message to an external file and use the $SNDJ BC system service to manage 
print jobs and define queue characteristics. 


16.8.3 Modifying Messages 


Message modification using MAIL$MESSAGE_ MODIFY involves setting flags 
that identify a message or group of messages as having certain characteristics. 
The following table summarizes bit offsets that modify flag settings: 


Symbol Meaning 
MAIL$V_replied Flagged as answered 
MAIL$V_marked Flagged for display purposes 


16.8.4 Copying and Moving Messages 


You can copy messages between folders within a mail file or between folders in 
different mail files using MAIL$¢MESSAGE_COPY. The Mail utility copies the 
message from the source folder to the destination folder leaving the original 
message intact. 
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Similarly, you can move messages between folders within a mail file or between 
folders in different mail files using MAIL$¢MESSAGE_ COPY with the item code 
MAIL$ MESSAGE _ DELETE. The Mail utility moves a message by copying the 
message from the source folder to the destination folder. You must specify a folder 
name. 


When you move a message to another folder within the same mail file, you are 
changing the message's secondary key—its folder name. 


16.8.4.1 Creating Folders 


You can create a folder in a specified mail file whenever you attempt to copy 
or move a message to a nonexistent folder. When you create a folder, you are 
assigning a previously nonexistent folder name to a message as its secondary key. 


Your application can include a user-written folder action routine that notifies you 
that the folder does not exist and accepts input to create the folder. 


16.8.4.2 Deleting Folders 


You can delete a folder by moving all of the messages within the source folder 
to another folder in the same mail file or to a folder in another mail file. In this 
case, the Mail utility associates messages that are moved with a new folder name. 


You can also delete a folder by deleting all of the messages in a folder. The Mail 
utility associates messages designated for deletion with the wastebasket folder 
name. 


In either case, the original folder name—the secondary key—no longer exists. 


16.8.4.3 Creating Mail Files 


Similarly, you can create a mail file whenever you attempt to copy or move a 
message to a nonexistent mail file. 


Your application can include a user-written mail file action routine that notifies 
you that the mail file does not exist and accepts input to create the mail file. 


Mail file creation involves creating the mail file and then copying or moving the 
message to the new mail file. If the message is shorter than 3 blocks, the Mail 
utility stores the message in the mail file. Otherwise, the Mail utility places a 
pointer to the message in the newly created mail file. 


16.8.5 Deleting Messages 


To delete a message, you need to know its message identification number. 
Applications can retrieve the message identification number by specifying the 
item code MAIL$¢ MESSAGE _ID when selecting a message or group of messages 
with MAIL$MESSAGE_ SELECT. 


When you delete all messages with the same secondary key (folder name) using 
MAIL$MESSAGE_DELETE and specifying the item code MAIL$ MESSAGE ID, 
you have deleted the folder. 


16.9 Send Context 


Send context processing involves creating and sending new and existing 
messages. Table 16-8 summarizes send routines. 
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Table 16-8 Send Routines 


Routine Description 

MAIL$SEND_ABORT Aborts a send operation 
MAIL$SEND_ADD_ADDRESS Adds an addressee to the address list 
MAIL$SEND_ADD_ATTRIBUTE Constructs the message header 
MAIL$SEND_ADD_BODY PART Constructs the body of the message 
MAIL$SEND_BEGIN Initiates send processing 
MAIL$SEND_END Terminates send processing 
MAIL$SEND_MESSAGE Sends a message 


Initiating the Send Context 

You can invoke the send context directly if you are creating a new message. 
Otherwise, to access an existing message, you must open the mail file that 
contains the message, select the message, and retrieve it. 

Terminating the Send Context 

You must terminate the send context explicitly using MAIL$SEND_END. 


16.9.1 Sending New Messages 
You can send new or existing messages to yourself and other users. 


16.9.1.1 Creating a Message 
You create new messages using send context routines. If you want to create and 
send a new message, you do not need to initiate any other context. As mentioned 
earlier, a message consists of two parts—the message header and the message 
bodypart. 


Constructing a message involves building each part of the message separately 
using the following routines: 


e MAIL$SEND_ADD_ATTRIBUTE 
e MAIL$SEND_ADD_BODYPART 


16.9.1.1.1 Constructing the Message Header [Each field of the message header 
is a message attribute. You can specify one or more attributes for inclusion in 
the message header using MAIL$SEND_ADD_ATTRIBUTE. During successive 
calls to MAIL$SEND_ADD_ ATTRIBUTE, an application specifies the specific 
message attribute to be constructed. 


If you do not specify the From: or To: fields, the Mail utility provides this 
information from the address list. 


16.9.1.1.2 Constructing the Body of the Message To construct a message, an 
application must specify a series of calls to MAIL$SEND_ADD_BODYPART to 
build a message from successive text records contained in a buffer or file. 


If the body of the message is located in a file, you can build the bodypart with one 
call to MAIL$SEND_ADD_BODYPART by specifying its file name. 
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16.9.1.2 Creating an Address List 
You must create an address list in order to send a message. The address list is 
a file or buffer of addressees to whom you want to send the message. Each entry 
in the address list is a valid user name on your system or on another system 
connected to your system by DE Cnet. 


Adding User Names to the Address List 

User names are added one at a time to the address list using one or more calls to 
MAIL$SEND_ADD_ADDRESS. 

User Name Types 


There are two types of user names—direct and carbon copy addressees. Direct 
and carbon copy addressees correspond to user names in the To: and CC: fields of 
the message header. 


16.9.2 Sending Existing Messages 


Sending an existing message involves many tasks as well as initiating the mail 
file context and message context. The following table summarizes the tasks and 
routines involved in sending an existing message: 


Task Routine 
Open a mail file. MAIL$MAILFILE_OPEN 
Select the message. MAIL$MESSAGE_SELECT 
Retrieve the message. MAIL$MESSAGE_GET 
Construct the message. 
Construct the message MAIL$SEND_ADD_ATTRIBUTE 
header. 
Construct the message MAIL$SEND_ADD_BODY PART 
bodypart. 
Create an address list. MAIL$SEND_ADD_ADDRESS 
Send the message. MAIL$SEND_MESSAGE 


16.9.3 Send Action Routines 


Once you have created an address list and constructed a message, you can send 
the message using MAIL$SEND_MESSAGE. Optional success and error action 
routines handle signaled success and error events in a synchronous manner. 


For example, If DECnet returns messages indicating that it might not be possible 
to complete a send operation to some users in your address list, a user-specified 
send action routine might prompt the sender for permission to continue the send 
operation. 

16.9.3.1 Success Action Routines 
A success action routine performs a task upon successful completion of a send 
operation. 

16.9.3.2 Error Handling Routines 


An error action routine is a user-written error handler that signals error 
conditions during a send operation. 
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16.9.3.3 Aborting a Send Operation 


Under certain circumstances, you might want to terminate a send operation 
in progress using MAIL$SEND_ABORT. In this instance, you can use an 
asynchronous system trap (AST) routine that contains a call to MAIL$SEND_ 
ABORT to abort the send operation whenever the user presses Ctrl/C. 


16.10 User Profile Context 


The user profile processing context functions as a system management tool 
for customizing the programming and interactive mail environments. It lets 
individual users modify their default processing characteristics. 


The user profile database VMSMAIL_PROFILE.DATA contains information that 
application programs and the Mail utility use for processing in any context. 


Table 16-9 summarizes the user context routines. 


Table 16-9 User Profile Context Routines 


Routine Description 

MAIL$USER_BEGIN Initiates user profile context 

MAIL$USER_DELETE_INFO Deletes a user profile entry 

MAIL$USER_END Terminates user profile context 

MAIL$USER_GET_INFO Retrieves information about a user from the user 
profile 

MAIL$USER_SET_INFO Adds or modifies a user profile entry 


Initiating the User Context 
You can invoke the user context directly. 


Terminating the User Context 


You must terminate the user context with MAIL$USER_END. Terminating the 
user context deallocates virtual memory. 


16.10.1 User Profile Entries 


A user profile entry is a dynamic record. The Mail utility creates a user profile 
entry automatically for the calling process if it does not exist. The callable and 
user interfaces of the Mail utility use the data contained in the user profile entry. 
The user profile consists of fields as described in the sections that follow. 


MAIL Subdirectory 

A MAIL subdirectory is the location—that is, the disk and directory 
specification—of your mail files. When you define a MAIL subdirectory, you are 
creating a subdirectory in which the specified mail file and associated external 
messages are to reside. For example: 


SDISK5: [MAILUSER. COMMON. MAIL] 


The subdirectory [.common.mail] represents the MAIL subdirectory specification 
defined in the user profile entry. This subdirectory contains the mail file (for 
example, MAIL.MAI) and any external messages associated with the mail file. 
The disk and directory specification $DISK5:[MAILUSER] is defined in the user 
authorization file (UAF). 
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Flags 

User profile flags can be set to enable or disable automatic purging of deleted 
mail, automatic self-copy when forwarding, replying, or sending messages, and 
use of the CC prompt. 


Form 

The form field of the user profile entry defines the default print form to be used 
by print batch jobs. The string you specify as the default form must match a valid 
print form in use on your system. 


Forwarding Address 

A forwarding address lets you receive messages to your account on another 
system or to have your messages sent to another user either on your system or 
another system. You must specify valid node names and user names. 


Personal Name 

A personal name is a user-specified character string. For example, a personal 
name might include your entire name and phone number. Any phrase beginning 
with alphabetic characters up to a maximum of 127 alphanumeric characters is 
valid. However, consecutive embedded spaces should not be used. 


Queue Name 


The queue name field defines the default print queue on your system where your 
print jobs are sent. 


16.10.1.1 Adding Entries to the User Profile Database 
Ordinarily, the Mail utility creates a user profile entry for the calling process 
if one does not already exist. A system management application might create 
entries for other users. When you specify the item code MAIL$ USER_CREATE_ 
IF using MAIL$USER_SET_INFO, the Mail utility creates a user profile entry if 
it does not already exist. 


16.10.1.2 Modifying or Deleting User Profile Entries 
The calling process can modify, delete, or retrieve its own user profile entry 
without privileges. 


The following table summarizes the privileges required to modify or delete user 
profile entries that do not belong to the calling process: 


Procedure Privilege Function 

MAIL$USER_SET_INFO SYSPRV Modifies another user’s 
profile entry 

MAIL$USER_GET_INFO SYSNAM or SYSPRV Retrieves information about 


another user 


16.11 Input Item Codes 


Input item codes direct the called routine to read data from a buffer or file and 
perform a task. Table 16-10 summarizes input item codes. 
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ltem Code 


Function 


Mail File Context 


MAIL$ MAILFILE_DEFAULT_NAME 
MAIL$ MAILFILE_FOLDER_ROUTINE 
MAIL$ MAILFILE_FULL_CLOSE 
MAIL$ MAILFILE_NAME 


MAIL$ MAILFILE_RECLAIM 


MAIL$ MAILFILE_USER_DATA 


MAIL$ MAILFILE_WASTEBASKET_NAME 


Specifies the location (disk and directory) of the default 
mail file MAIL.MAI. 


Displays folder names within a specified mail file. 


Requests that the wastebasket folder be purged and 
that a convert/reclaim operation be performed, if 
necessary. 


Specifies the name of a mail file to be opened. 


Overrides the deleted bytes threshold and requests a 
reclaim operation. 


Passes a longword of user context data to an action 
routine. 


Specifies a new name for the wastebasket in a specified 
mail file. 


Message Context 


MAIL$ MESSAGE_AUTO_NEWMAIL 


MAIL$ MESSAGE_BACK 
MAIL$ _MESSAGE_BEFORE 
MAIL$ MESSAGE_CC_SUBSTRING 


MAIL$ MESSAGE CONTINUE 
MAIL$ MESSAGE _DEFAULT_NAME 
MAIL$ MESSAGE DELETE 


MAIL$ MESSAGE_FILE_ACTION 
MAIL$ _MESSAGE_FILE_CTX 
MAIL$_MESSAGE_FILENAME 
MAIL$ MESSAGE_FOLDER_ACTION 
MAIL$ MESSAGE_FLAGS 


MAIL$ MESSAGE_FLAGS MBZ 
MAIL$ _MESSAGE_FOLDER 


MAIL$ MESSAGE _FROM_SUBSTRING 


Places newly read messages in the Mail folder 
automatically. 


Returns the first record of the preceding message. 
Selects a message before a specified date. 


Specifies a character string that must match a node or 
user name substring in the CC: field of the specified 
message. 


Returns the next text record of the current message. 
Specifies the default mail file specification. 


Deletes a message in the current folder after the 
message has been copied to a new folder. 


Specifies a user-written routine that is called if a mail 
file is to be created. 


Specifies mail file context received from 
MAIL$MAILFILE_BEGIN. 


Specifies the name of a mail file to which the message 
is to be moved. 


Specifies a user-written routine that is called if a folder 
is to be created. 


Specifies MAIL system flags to use when selecting 
messages. 


Specifies MAIL system flags that must be zero. 


Specifies the name of the target folder for moving 
messages. 


Specifies a character string that must match a node or 
user name substring in the From: field of the specified 
message. 


(continued on next page) 


Mail Utility (MAIL) Routines MAIL—19 


Mail Utility (MAIL) Routines 
16.11 Input Item Codes 


Table 16-10 (Cont.) Input Item Codes 


Item Code 


Function 


Message Context 


MAIL$ MESSAGE_ID 
MAIL$ MESSAGE_NEXT 


MAIL$ MESSAGE_SINCE 


MAIL$ MESSAGE _SUB) SUBSTRING 


MAIL$ MESSAGE_TO_ SUBSTRING 


MAIL$ MESSAGE_USER_DATA 


Specifies the message identification number of the 
message on which an operation is to be performed. 


Returns the first record of the message following the 
current message. 


Selects a message received on or after a specified date. 


Specifies a character string that must match a node 
or user name substring in the Subject: field of the 
specified message. 


Specifies a character string that must match a 
substring in the To: field of the specified message. 


Specifies a longword to be passed to the folder and mail 
file action routines. 


Send Context 


MAIL$ SEND_CC_LINE 
MAIL$ SEND_DEFAULT_NAME 


MAIL$ SEND_ERROR_ENTRY 


MAIL$ SEND FID 
MAIL$ SEND_FILENAME 


MAIL$ SEND_FROM_LINE 


MAIL$ SEND_PERS NAME 
MAIL$ SEND_NO PERS NAME 


MAIL$ SEND_RECORD 
MAIL$ SEND_SIGFILE 


MAIL$ SEND_NO SIGFILE 
MAIL$ SEND SUBJ ECT 
MAIL$ SEND SUCCESS ENTRY 


MAIL$ SEND_TO_LINE 
MAIL$ SEND_USER_DATA 

MAIL$ SEND_USERNAME 

MAIL$ SEND_USERNAME_TYPE 
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Specifies the CC: field text. 


Specifies the default file specification of a text file to be 
opened. 


Specifies a user-written routine to process errors that 
occur during a send operation. 


Specifies the file identifier. 


Specifies the input file specification of a text file to be 
opened. 


Specifies the From: field text. 


Specifies the personal name string. 
Specifies that no personal string be used. 


Specifies the descriptor of a text record to be added to 
the body of a message. 


Specifies a full OpenVMS file specification of the 
signature file to be used in the message. 


Specifies that no signature file be used. 
Specifies the Subject: field text. 


Specifies a user-written routine to process successfully 
completed events during a send operation. 


Specifies the To: field text. 
Specifies a longword passed to the send action routines. 
Adds a specified user name to the address list. 


Specifies the type of user name added to the address 
list. 


(continued on next page) 
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ltem Code 


Function 


User Context 


MAIL$_USER_CREATE_IF 
MAIL$ USER_FIRST 


MAIL$ USER_NEXT 


MAIL$ USER_SET AUTO PURGE 
MAIL$ USER_SET_NO AUTO PURGE 


MAIL$ USER_SET_CC_PROMPT 
MAIL$ USER_SET_NO_CC PROMPT 


MAIL$ USER_SET_COPY_FORWARD 
MAIL$ USER_SET_NO COPY_FORWARD 


MAIL$ USER_SET_COPY_REPLY 
MAIL$ USER_SET_NO COPY_REPLY 


MAIL$ USER_SET_COPY_SEND 
MAIL$ USER_SET_NO COPY SEND 


MAIL$ USER_SET EDITOR 
MAIL$ USER_SET_NO EDITOR 


MAIL$ USER_SET_FORM 
MAIL$ USER_SET_NO FORM 


MAIL$ USER_SET_ FORWARDING 
MAIL$ USER_SET_NO FORWARDING 


MAIL$ USER_SET_NEW_MESSAGES 


MAIL$ USER_SET_PERSONAL_NAME 
MAIL$_USER_SET_NO_ PERSONAL NAME 


MAIL$ USER_SET_QUEUE 
MAIL$ USER_SET_NO QUEUE 


MAIL$ USER_SET_SIGFILE 


MAIL$ USER_SET_NO SIGFILE 


MAIL$ USER_SET_SUB_DIRECTORY 
MAIL$ USER_SET_NO SUB_ DIRECTORY 


MAIL$ USER_USERNAME 


Creates a user profile entry. 


Returns information about the first user in the user 
profile database. 


Returns information about the next user in the user 
profile database. 


Sets the automatic purge flag. 
Clears the automatic purge flag. 


Sets the CC prompt flag. 
Clears the CC prompt flag. 


Sets the copy self forward flag. 
Clears the copy self forward flag. 


Sets the copy self reply flag. 
Clears the copy self reply flag. 


Sets the copy self send flag. 
Clears the copy self send flag. 


Specifies the default editor. 
Clears the default editor field. 


Specifies the default print form string. 
Clears the default print form field. 


Specifies the forwarding address string. 
Clears the forwarding address field. 


Specifies the new messages count. 


Specifies the personal name string. 
Clears the personal name field. 


Specifies the default print queue name string. 
Clears the default print queue name field. 


Specifies a signature file specification for the specified 
user. 


Clears a signature file field for the specified user. 


Specifies a MAIL subdirectory. 
Clears the MAIL subdirectory field. 


Points to the user name string to specify the user 
profile entry to be modified. 


16.12 Output Item Codes 


Output item codes direct the called routine to return data to a buffer or file which 
is then available for use by the application. Table 16-11 summarizes output item 


codes. 
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Table 16-11 Output Item Codes 


Item Code 


Function 


Mail File Context 


MAIL$ MAILFILE_INDEXED 
MAIL$ MAILFILE_DIRECTORY 


MAIL$ MAILFILE_RESULTSPEC 
MAIL$ MAILFILE_WASTEBASKET 


MAIL$ MAILFILE_DELETED_BYTES 


MAIL$ MAILFILE_MESSAGES DELETED 


MAIL$ MAILFILE_DATA_RECLAIM 
MAIL$ MAILFILE_DATA_SCAN 
MAIL$ MAILFILE_INDEX_RECLAIM 
MAIL$ MAILFILE_TOTAL_RECLAIM 


Determines whether the mail file format is indexed. 


Returns the mail file subdirectory specification to the 
caller. 


Returns the result mail file specification. 


Returns the wastebasket folder name for the specified 
file. 


Returns the number of deleted bytes in a specified mail 
file. 


Returns the number of deleted messages. 
Returns the number of data buckets reclaimed. 
Returns the number of data buckets scanned. 
Returns the number of index buckets reclaimed. 
Returns the total number of bytes reclaimed. 


Message Context 


MAIL$ MESSAGE_BINARY_DATE 
MAIL$ MESSAGE_CC 


MAIL$ MESSAGE_CURRENT_ID 


MAIL$ MESSAGE_DATE 
MAIL$ MESSAGE_EXTID 


MAIL$ MESSAGE_FILE_CREATED 
MAIL$ MESSAGE_FOLDER_CREATED 
MAIL$ MESSAGE_FROM 


MAIL$ MESSAGE_RECORD 
MAIL$ MESSAGE_RECORD_TYPE 
MAIL$ MESSAGE_REPLY_PATH 
MAIL$ MESSAGE_RESULTSPEC 
MAIL$ MESSAGE_RETURN_FLAGS 


MAIL$ MESSAGE SELECTED 
MAIL$ MESSAGE_SENDER 
MAIL$ MESSAGE_SIZE 
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Returns the date and time received as a binary value. 


Returns the text in the CC: field of the current 
message. 


Returns the message identification number of the 
current message. 


Returns the message creation date string. 


Returns the external message identification number of 
the current message. 


Returns the value of the mail file created flag. 
Returns the value of the folder created flag. 


Returns the text in the From: field of the current 
messsage. 


Returns a record from the current message. 
Returns the record type. 

Returns the reply path. 

Returns the resultant mail file specification. 


Returns the MAIL system flag value of the current 
message. 


Returns the number of selected messages. 

Returns the name of the sender of the current message. 

Returns the size in records of the current message. 
(continued on next page) 
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ltem Code 


Function 


Message Context 


MAIL$ MESSAGE SUBJ ECT 


MAIL$ MESSAGE _TO 


Returns the text in the Subject: field of the specified 
message. 


Returns the text in the To: field of the specified 
message. 


Send Context 


MAIL$ SEND_COPY_FORWARD 
MAIL$ SEND_COPY_REPLY 
MAIL$ SEND_COPY_SEND 
MAIL$ SEND_RESULTSPEC 


MAIL$ SEND_USER 


Returns the value of the caller’s copy forward flag. 
Returns the value of the caller’s copy reply flag. 
Returns the value of the caller’s copy send flag. 


Returns the resultant file specification of the file to be 
sent. 


Returns the process owner's user name. 


User Context 


MAIL$ USER_AUTO_PURGE 
MAIL$_USER_CAPTIVE 

MAIL$ USER_CC_PROMPT 
MAIL$ USER_COPY_FORWARD 
MAIL$ _USER_COPY_REPLY 
MAIL$ USER_COPY_SEND 
MAIL$_USER_EDITOR 
MAIL$_USER_FORM 

MAIL$ USER_FORWARDING 
MAIL$ USER_FULL_DIRECTORY 


MAIL$ USER_NEW_MESSAGES 
MAIL$ _USER_PERSONAL_NAME 
MAIL$ USER_QUEUE 

MAIL$ _USER_RETURN_USERNAME 
MAIL$ USER_SIGFILE 

MAIL$ USER_SUB_DIRECTORY 


Returns the value of the automatic purge mail flag. 
Returns the value of the UAF captive flag. 

Returns the value of the CC prompt flag. 

Returns the value of the copy self forward flag. 
Returns the value of the copy self reply flag. 
Returns the value of the copy self send flag. 
Returns the name of the default editor. 

Returns the default print form string. 

Returns the forwarding address string. 


Returns the complete directory path of the mail file 
subdirectory. 


Returns the new message count. 

Returns the personal name string. 

Returns the default queue name string. 
Returns the user name string. 

Returns the default signature file specification. 
Returns the subdirectory specification. 


16.13 Using the MAIL Routines: Examples 


This section provides examples of using the MAIL routines in various 
programming scenarios including the following: 


e Example 16-1 is a C program that sends a Mail message to another user. 


e Example 16-2 is a C program that displays a user’s folders and returns how 
many messages are in each folder. 


e Example 16-3 is a C program that displays fields in the user's Mail profile. 
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Example 16-1 Sending a File 


/* send _message.c */ 


include <stdio> 
include <descrip> 
include <ssdef> 
include <maildef> 
include <nam> 


typedef struct itmlst 


short buffer length; 

short item_code; 

long buffer_address; 

long return_length_address; 
ITMLST; 

int 

send context = 0 


1 


ITMLST 

nulllist[] = { {0,0,0,0} }; 
int 

getline(char *line, int max) 


if (fgets(line, max, stdin) == NULL) 


return 0; 
else 
return strlen(line) ; 


int 
main (int argc, char *argv[]) 


{ 


char 
to_user [NAM$C_MAXRSS], 
subject_line [NAMSC_MAXRSS], 
file [NAMS$C_MAXRSS] , 
resultspec [NAM$C_MAXRSS] 


long resultspeclen; 


int 
status = SS$ NORMAL, 
file len = 0, 


subject_line len = 0, 
to_user_ len = 0 


! 
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ITMLST 
address itmlst[] = { 
sizeof (to_user), MAILS SEND USERNAME, to user, &to user len}, 
0,0,0,0}}, 
bodypart_itmlst[] = { 
Feri file), MAILS SEND FILENAME, file, &file len}, 
0,0,0,0}}, 
out_bodypart_itmlst[] = { 


sizeof (resultspec), MAIL$ SEND RESULTSPEC, resultspec, &resultspeclen}, 


0,0,0,0}}, 
attribute itmlst [] 


sizeof (subject_line), MAILS SEND SUBJECT, subject line, &subject line len}, 


sia to_user), MAILS SEND TO LINE, to_user, &to user len}, 


0,0,0,0}} 


if 


status = mailSsend_begin(&send_context, &nulllist, &nulllist); 
if (status != SS$ NORMAL) 
exit (status) ; 


/* Get the destination and add it to the message */ 
printf("To: "); 
to_user[getline(to user, NAMSC_MAXRSS) - 1] = ‘\0'; 


address itmlst[0].buffer length = strlen(to_user) ; 
address itmlst[0].buffer_ address = to_user; 


status = mail$send_add_address(&send_context, address itmlst, &nulllist) ; 


if (status != SS$_ NORMAL) 
return(status) ; 


/* Get the subject line and add it to the message header */ 
printf ("Subject: "); 
subject_line[getline(subject_line, NAM$C_MAXRSS) - 1] = ‘\0'; 
* Displayed TO: line */ 

ttribute_itmlst[0].buffer length = strlen(to_user) ; 
ttribute_itmlst[0].buffer address = to_user; 


oo 


* Subject: line */ 
ttribute_itmlst[1].buffer_ length = strlen(subject_line) ; 
ttribute_itmlst[1].buffer_address = subject line; 


9 o~ © MY ™~ 


if (status != SS$ NORMAL) 


return(status) ; 


/* Get the file to send and add it to the bodypart of the message */ 
printf ("File: "); 
file[getline(file, NAMSC_MAXRSS) - 1] = ‘\0'; 


bodypart_itmlst[0].buffer length = strlen(file) ; 
bodypart_itmlst[0].buffer address = file; 


status = mailSsend_add_attribute(&send_context, attribute itmlst, &nulllist); 


status = mail$send_add_bodypart (&send_context, bodypart_itmlst, out_bodypart_itmlst) ; 


if (status != SS$ NORMAL) 
return (status) ; 


resultspec[resultspeclen] = '\0’; 
printf("Full file spec actually sent: [%s]\n", resultspec) ; 


(continued on next page) 
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} 


/* Send the message */ 
status = mailSsend_message(&send_context, nulllist, nulllist); 
if (status != SS$ NORMAL) 

return(status) ; 


/* Done processing witht the SEND context */ 
status = mail$send_end(&send_context, nulllist, nulllist) ; 
if (status != SSS NORMAL) 

return(status) ; 


return (status); 


Example 16-2 shows a C program that displays folders. 


Example 16-2 Displaying Folders 


/* show folders.c */ 


include <stdio> 
include <descrip> 
include <ctype> 
include <ssdef> 
include <maildef> 


typedef struct itmlst 


short buffer length; 

short item_code; 

long buffer_address; 

long return_length address; 
ITMLST; 


struct node 


struct node *next; /* Next folder name node */ 
char *folder_name; /* Zero terminated folder name */ 
int 


folder routine(struct node *list, struct dsc$descriptor *name) 
if (name->dsc$w_length) 


while (list->next) 
list = list->next; 


list->next = malloc(sizeof (struct node) ); 

list = list->next; 

list->next = 0; 

list->folder name = malloc(name->dsc$w_length + 1); 


strncpy (list->folder name, name->dsc$a pointer,name->dsc$w_ length) ; 


list->folder name [name->dsc$w_ length] = '\0'; 


return (SS$ NORMAL) ; 
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Example 16-2 (Cont.) Displaying Folders 


main (int argc, char *argv[]) 


{ 


struct node list = {0,0}; 
int 
message context = 0, 
file context = 0, 
messages selected = 
total folders = 0, 
total messages = 0 


ITMLST 

nulllist[] = {{0,0,0,0 

message in itmlst[] = 
[o,0,0,0)} ,MAILS$ MESSAGE FILE CTX, &file context,0}, 
0,0,0,0}} 

mailfile info itmlst [] 

i ,MAIL$ MATLFILE _ FOLDER ROUTINE, folder routine, 0}, 


ee 


! 


4,MAIL$ MAILFILE - USER_DATA, &list, 0}, 
0,0,0,0}}, 
message select in itmlst[] = { 
fs ,MAIL$ MESSAGE FOLDER,0,0}, 
0,0,0,0}}, 
message select out itmlst as 
am 


G0,0,0} 13 
if (mail$mailfile begin(&file context, nulllist, nulllist) == SS$ NORMAL) { 
if (mail$mailfile open(&file context, nulllist, nulllist) == sss _ NORMAL) { 


if (mail$mailfile info file(&file context, 
mailfile info itmlst, 
nulllist) == SS$ NORMAL 
if (mail$message begin (&message_ context, 
message_in itmlist, 
nulllist) == SS$ NORMAL) { 
struct node *tmp = &list; 


while (tmp->next) { 
tmp = tmp->next; 
message select _in itmlst[0] .buffer address = tmp->folder name; 
message select_in itmlst[0] .buffer length = strlen(tmp->folder_ name) ; 
if (mailSmessage select (&message_ context, 
message select _in itmlst, 
message select out _itmlst) == SS$ NORMAL) { 
printf ("Folder %s has %d messages\n", 
tmp->folder name, messages selected) ; 
total_messages += messages selected; 
total folders++; 
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printf ("Total of %d messages in %d folders\n",total_messages, total folders) ; 


mail$message_end(&message context, nulllist, nulllist) ; 
mailsmailfile close(&file context, nulllist, nulllist) ; 


mailsmailfile_end(&file context, nulllist, nulllist) ; 


} 


Example 16-3 shows a C program that displays user profile information. 


Example 16-3 Displaying User Profile Information 


/* show profile.c */ 


#include <stdio> 
#include <ssdef> 
#include <jpidef> 
#include <maildef> 
#include <stsdef> 
#include <ctype> 
#include <nam> 


struct itmlst 


short buffer length; 

short item_code; 

long buffer address; 

long return_length_address; 


bi 
int 
user_context = 0 
struct 
itmlst nulllist[] = { {0,0,0,0} }; 
int 
Main (int argc, char *argv[]) 
int 
userlen = 0, 
/* return length of strings */ 


editor len = 0, 

form len = 0, 
forwarding len = 0, 
full directory len = 0, 
personal name_len = 0, 
queue_len = 0, 


/* Flags */ 


auto purge = 0, 
cc_prompt = 0 
copy forward 
copy reply = 
copy_send = 0 


= 0; 
0, 


r 
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Example 16-3 (Cont.) Displaying User Profile Information 


char 
user [13], 


editor [NAM$C_MAXRSS] , 
form[NAM$C_MAXRSS] , 
forwarding [NAMSC_MAXRSS] , 
full directory [NAMSC_MAXRSS], 
personal name [NAM$C_MAXRSS], 
queue [NAMSC_MAXRSS] 


1 


short 


new_messages = 0 


I 


struct itmlst 
jpi_list{] = { 
sizeof(user) - 1, JPI$ USERNAME, user, éuserlen}, 


0,0,0, 


O}}, 


user_itmlst [ 


ie MAIL$ USER USERNAME, 


sizeof (full directory) ,MA 


sizeof (new_messages), MAIL$ USER_NEW 


0, 0}, 


/* Full directory spec */ 


/* New message c 


/* Forwarding fi 


sizeof (forwarding), MAIL 


sizeof (personal name), MAIL$ USER_PE 


/* Personal name 


/* Editor field 


ount */ 
MESSAGES, &new messages, 0}, 


eld */ 
field */ 


si 


sizeof (editor), MAIL$ USER EDITOR, editor, &editor len}, 


/* CC prompting 


flag */ 


sizeof(cc_prompt), MAIL$ USER CC PROMPT, &cc_prompt, 0}, 


sizeof (copy reply 


/* Copy send fla 


/* Copy reply £ 


/* Copy forward 


g */ 


ag */ 


IAIL$ USER_COPY REPLY, &copy reply, 0}, 


flag */ 


sizeof (copy forward), MAIL$ USER_COPY FORWARD, &copy forward, 0}, 


sizeof (auto_purge 


/* Auto purge 


/* Queue field * 


flag */ 
IAIL$ USER AUTO PURGE, &auto purge, 0}, 


/ 


sizeof (queue), MAIL$ USER QUEUE, queue, &queue_len}, 


/* Form field */ 


{ 
{ 
{ 
{ 
{ 
{ 
{sizeof (copy_send), MAIL$ USER_COPY_SEND, scopy send, 0}, 
{ 
{ 
{ 
{ 
{ 


sizeof (form), MAIL$ USER FORM, form, &form len}, 


{0,0,0,0}}; 
int 
SS$_ NORMAL 


status = 


1 


/* Get a mail user context */ 

status = MAILSUSER_BEGIN(&user_context, 
é&nulllist, 
énulllist) ; 


if (status 


!= S$S$ NORMAL) 


return (status) ; 


if (argc > 


1) { 


strepy (user, argv[1] ); 


else 


{ 


sys$getjpiw(0,0,0,jpi_list,0,0,0); 
user[userlen] = '\0'; 


1 


L$ USER FULL DIRECTORY, full directory, &full_directory len}, 


$ USER FORWARDING, forwarding, &forwarding len}, 


RSONAL NAME, personal name, &personal_name len}, 


(continued on next page) 
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Example 16-3 (Cont.) Displaying User Profile Information 


while (isspace (user [--userlen] ) 
user[userlen] = '\0'; 


user_itmlst [0] .buffer_length = strlen(user) ; 
user itmlst [0] .buffer_ address = user; 


status = MAILSUSER_GET_INFO(&user_context, user_itmlst, out_itmlst) ; 
if (status != SS$ NORMAL) 
return (status); 


/* Release the mail USER context */ 
status = MAILSUSER_END(&user_context, &nulllist, &nulllist) ; 
if (status != SS$ NORMAL) 

return(status) ; 


/* display the information just gathered */ 


full directory [full_directory len] = ‘\0'; 
printf ("Your mail file directory is %s.\n", full directory) ; 
printf ("You have %d new messages.\n", new_messages) ; 


forwarding[forwarding len] = '\0'; 
if (strlen(forwarding) == 0) 

printf ("You have not set a forwarding address.\n"); 
else 


printf("Your mail is being forwarded to %s.\n", forwarding) ; 


personal _name[personal_name_len] = '\0'; 
printf ("Your personal name is \"%s\"\n", personal_name) ; 


editor [editor_len] = '\0'; 
if (strlen(editor) == 0) 

printf ("You have not specified an editor.\n"); 
else 

printf ("Your editor is %s\n", editor); 


printf ("CC prompting is %s.\n", (cc_prompt == TRUE) ? "disabled" : "enabled") ; 


printf ("Automatic copy to yourself on"); 
if (copy_send == TRUE) 
printf (" SEND") ; 
if (copy_reply == TRUE) { 
if (copy send == TRUE) 
printf (","); 
printf (" REPLY") ; 


if (copy forward == TRUE) { 
if ((copy_reply == TRUE) || (copy send == TRUE) ) 
printf(","); 
printf (" FORWARD") ; 


if ((copy_reply == FALSE) && (copy _send == FALSE) && (copy forward == FALSE) ) 
printf (" Nothing") ; 


printf ("\n") ; 
printf ("Automatic deleted message purge is %s.\n", (auto purge == TRUE) ? "disabled" : "enabled") ; 
queue [queue_len] = ‘\0’; 


if (strlen(queue) == 0) 
printf("You have not specified a default queue. \n"); 


else 
printf("Your default print queue is %s.\n", queue); 
form[form_len] = ‘\0'; 


if (strlen(form) == 0) 

printf ("You have not specified a default print form.\n") ; 
else 

printf ("Your default print form is %s.\n", form); 
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16.14 MAIL Routines 


This section describes the individual MAIL routines. Input and output item 
list arguments use item descriptor fields structured as shown in the following 
diagram: 


ZK-1705-GE 


Item Descriptor Fields 

buffer length 

For input item lists, this word specifies the length (in bytes) of the buffer that 
supplies the information needed by the routine to process the specified item code. 


For output item lists, this word contains a user-supplied integer specifying the 
length (in bytes) of the buffer in which the routine is to write the information. 


The required length of the buffer depends on the item code specified in the item 
code field of the item descriptor. If the value of buffer length is too small, the 
routine truncates the data. 


item code 

For input item lists, a word containing a user-supplied symbolic code that 
specifies an option for the Mail utility operation. For output item lists, a word 
containing a user-supplied symbolic code specifying the item of information that 
the routine is to return. Each programming language provides an appropriate 
mechanism for defining this information. 


buffer address 

For input item lists, a longword containing the address of the buffer that supplies 
information to the routine. For output item lists, a longword containing the user- 
supplied address of the buffer in which the routine is to write the information. 


return length address 

This field is not used for input item lists. For output item lists, this field contains 
a longword specifying the user-supplied address of a longword in which the 
routine writes the actual length in bytes of the information it returns. 
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MAIL$MAILFILE_BEGIN—Start Mail File Processing 


Format 


Returns 


Arguments 


Initiates mail file processing. 


MAIL$MAILFILE_BEGIN context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to other mail file routines. The context 
argument is the address of a longword that contains mail file context information. 


You should specify the value of this argument as 0 in the first of a sequence of 
calls to mail file routines. In the following calls, you should specify the mail file 
context value returned by this routine. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by a longword value of 0. 
For this routine, there are no input item codes. 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 
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The only output item code for this routine is the MAIL$ MAILFILE_MAIL_ 
DIRECTORY item code. When you specify MAIL$ MAILFILE_MAIL_ 
DIRECTORY, MAIL$MAILFILE_BEGIN returns the mail directory specification 
to the caller. The buffer address field of the item descriptor points to a buffer 
that receives a character string O to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$MAILFILE_BEGIN creates and initiates a mail file context for calls to 
other mail file routines. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition value returned by LIB$GET_VM, $GET]J PIW, and $GETSYI. 
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MAIL$MAILFILE_-CLOSE—Close the Current Mail File 


Format 


Returns 


Arguments 


Closes the currently open mail file. 


MAIL$MAILFILE_CLOSE context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$ MAILFILE_FULL_CLOSE specifies that 
MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it closes 
the mail file. If the number of bytes deleted by the purge operation exceeds a 
system-defined threshold, the Mail utility reclaims the deleted space from the 
mail file. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


The system-defined threshold is reserved by HP . 
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out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$ MAILFILE_DATA_RECLAIM 

When you specify MAIL$ MAILFILE_DATA RECLAIM, MAIL$MAILFILE_ 
CLOSE returns the number of data buckets reclaimed during the reclaim 
operation as a longword value. 


MAIL$_MAILFILE_DATA_SCAN 

When you specify MAIL$ MAILFILE_DATA SCAN, MAIL$MAILFILE_ CLOSE 
returns the number of data buckets scanned during the reclaim operation as a 
longword value. 


MAIL$ MAILFILE_INDEX_RECLAIM 

When you specify MAIL$ MAILFILE_INDEX_RECLAIM, MAIL$MAILFILE_ 
CLOSE returns the number of index buckets reclaimed during a reclaim operation 
as a longword value. 


MAIL$ MAILFILE_ MESSAGES DELETED 

When you specify MAIL$ MAILFILE_MESSAGES DELETED, 
MAIL$MAILFILE_CLOSE returns the number of messages deleted as a longword 
value. 


MAIL$ MAILFILE_TOTAL_RECLAIM 

When you specify MAIL$ MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_ 
CLOSE returns the number of bytes reclaimed during a reclaim operation as a 
longword value. 


If you specify the input item code MAIL$ MAILFILE_FULL_CLOSE, this 
procedure purges the wastebasket folder automatically before it closes the file. If 
the number of bytes deleted by this procedure exceeds the deleted byte threshold, 
the system performs a convert/reclaim operation on the file. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 
MAIL$ NOFILEOPEN No mail file is open. 

SS$ ACCVIO Access violation. 
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MAIL$MAILFILE_COMPRESS—Compress Mail File 


Format 


Returns 


Arguments 


Compresses a mail file. 


MAIL$MAILFILE_COMPRESS context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to various mail file routines. The 
context argument is the address of a longword that contains mail file context 
information returned by MAIL$MAILFILE_ BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MAILFILE_DEFAULT_NAME 

MAIL$ MAILFILE_DEFAULT_NAME specifies the default file specification the 
Mail utility should use when opening a mail file. The buffer address field 
points to a character string O to 255 characters long that defines the default file 
specification. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_COMPRESS uses the current default directory as the default 
mail file specification. 
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MAIL$MAILFILE_COMPRESS 


If you do not specify MAIL$ MAILFILE DEFAULT NAME, MAIL$MAILFILE_ 
COMPRESS creates the default mail file specification from the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 

e Subdirectory defined in the Mail user profile 

e Default file type of .MAI 

MAIL$_MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$ MAILFILE_FULL_CLOSE requests that the 


wastebasket folder be purged and that convert and reclaim operations be 
performed, if necessary. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ MAILFILE_NAME 

MAIL$ MAILFILE_NAME specifies the name of a mail file to be opened. The 
buffer that the buffer address field points to contains a character string of 0 to 
255 characters. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If you do not specify MAIL$ MAILFILE_ NAME, the default mail file name is 
MAIL. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Code 


MAIL$ MAILFILE_RESULTSPEC 

When you specify MAIL$ MAILFILE_RESULTSPEC, the Mail utility returns the 
resultant mail file specification. The buffer address field of the item descriptor 
points to a buffer that receives a character string O to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If you do not specify an input file, the MAIL$MAILFILE COMPRESS routine 
compresses the currently open Mail file. The MAIL$MAILFILE_COMPRESS 
routine signals informational messages concerning the phase of the compression. 
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Condition Values Returned 


SS$ NORMAL Normal successful completion. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOTISAM The message file is not an indexed file. 
RMS$ FNF The specified file cannot be found. 
RMS$ SHR The specified file is not shareable. 

SS$ ACCVIO Access violation. 

SS$_ IVDEVNAM The specified device name is invalid. 


Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME _ 
FILE, $CREATE, $OPEN, $PARSE, and $SEARCH. 
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MAIL$MAILFILE_END—End Mail File Processing 


Format 


Returns 


Arguments 


Terminates mail file processing. 


MAIL$MAILFILE END context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains MAILFILE context 
information returned by MAIL$MAILFILE_ BEGIN. 


If mail file processing is terminated successfully, the Mail utility sets the value of 
the argument context to 0. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_ MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$ MAILFILE_FULL_CLOSE requests that the 
wastebasket folder be purged and that convert and reclaim operations be 
performed, if necessary. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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Output Item 


Description 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


None. 


The MAIL$MAILFILE_END routine deallocates the mail file context created by 
MAIL$MAILFILE_BEGIN as well as any dynamic memory allocated by other 
mail file processing routines. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition value returned by LIB$FREE_VM. 
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MAIL$MAILFILE_INFO_FILE—Get Information About a Mail File 


Format 


Returns 


Arguments 


Obtains information about a specified mail file. 


MAIL$MAILFILE_INFO_FILE context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_ BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$ MAILFILE_DEFAULT_NAME 

MAIL$ MAILFILE_DEFAULT_NAME specifies the default mail file specification 
MAIL$MAILFILE_INFO_FILE should use when opening a mail file. The buffer 
address field of the item descriptor points to a character string of 0 to 255 
characters that defines the default mail file specification. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_INFO_FILE uses the current default directory as the default 
mail file specification. 
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Output Item 


If you do not specify MAIL$ MAILFILE_ DEFAULT NAME, MAIL$MAILFILE_ 
INFO FILE creates the default mail file specification from the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 
e Subdirectory defined in the Mail user profile 
e¢ Default file type of .MAI 


MAIL$_MAILFILE_FOLDER_ROUTINE 

MAIL$ MAILFILE_FOLDER_ROUTINE specifies an entry point longword 
address of a user-written routine that MAIL$¢MAILFILE_INFO_FILE should use 
to display folder names. MAIL$MAILFILE_INFO_FILE calls the user-written 
routine for each folder in the mail file. 


MAIL$_MAILFILE_NAME 

MAIL$ MAILFILE_NAME specifies the name of the mail file to be opened. The 
buffer address field points to a buffer that contains a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
If you do not specify MAIL$ MAILFILE_ NAME, the default mail file name is 
MAIL. 


MAIL$_MAILFILE_USER_DATA 
MAIL$ MAILFILE_USER_DATA specifies a longword that MAIL$MAILFILE_ 
INFO_FILE should pass to the user-defined folder name action routine. 


This item code is valid only when used with the item code MAIL$ MAILFILE_ 
FOLDER_ROUTINE. 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$ MAILFILE DELETED BYTES 

When you specify MAIL$ MAILFILE DELETED BYTES, MAIL$MAILFILE_ 
INFO FILE returns the number of deleted bytes in a specified mail file as 
longword value. 


MAIL$_MAILFILE_RESULTSPEC 

When you specify MAIL$ MAILFILE_RESULTSPEC, MAIL$MAILFILE_INFO_ 
FILE returns the resultant mail file specification. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Description 


Mail Utility Routines 
MAIL$MAILFILE_INFO_FILE 


MAIL$_ MAILFILE_WASTEBASKET 

When you specify MAIL$ MAILFILE_WASTEBASKET, MAIL$MAILFILE_ 
INFO_FILE returns the name of the wastebasket folder of the specified mail file. 
The buffer address field of the item descriptor points to a buffer that receives a 
character string O to 39 characters long. 


Specify a value from 0 to 39 in the buffer length field of the item descriptor. 


If you do not specify an input file, the MAIL$MAILFILE_INFO FILE returns 
information about the currently open mail file. 


Folder Action Routines 

If you use the item code MAIL$ MAILFILE_FOLDER_ROUTINE to specify a 
folder name routine, MAIL$MAILFILE_INFO_FILE passes control to a user- 
specified routine. For example, the folder action routine could display folder 
names. The user routine must return a 32-bit integer code. If the return code 
indicates success, the interaction between the user's routine and the callable 
routine can continue. 


The folder action routine passes a pointer to the descriptor of a folder name 
as well as the user data longword. A descriptor of zero length indicates that 
the MAIL$MAILFILE_INFO_FILE routine has displayed all folder names. 
If you do not specify the item code MAIL$¢ MAILFILE_FOLDER_ROUTINE, 
MAIL$MAILFILE_INFO_FILE does not call any folder action routines. 


Condition Values Returned 


MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOFILEOPEN The mail file is not open. 

MAIL$ NOTISAM The message file is not an indexed file. 
MAIL$ OPENIN Mail cannot open the file as input. 
SS$ ACCVIO Access violation. 


Any condition value returned by $CLOSE, $OPEN, $PARSE, and $SEARCH. 
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Mail Utility Routines 
MAIL$MAILFILE_MODIFY 


MAIL$MAILFILE_MODIFY—Modify Record of an Indexed File 


Format 


Returns 


Arguments 


Modifies the informational record of an indexed mail file, including the mail file 
name, the default mail file name, and the wastebasket name. 


MAIL$MAILFILE_MODIFY context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MAILFILE_DEFAULT_NAME 

MAIL$ MAILFILE_DEFAULT_NAME specifies the default file specification that 
the Mail utility should use when opening a mail file: The buffer address field 
points to a buffer that contains a character string of 0 to 255 characters that 
defines the default mail file specification. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If you specify the value 0 in the buffer length field of the item descriptor, 
MAIL$MAILFILE_MODIFY uses the current default directory as the default 
mail file specification. 
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Output Item 


Description 


Mail Utility Routines 
MAIL$MAILFILE_MODIFY 


If you do not specify MAIL$ MAILFILE_ DEFAULT NAME, MAIL$MAILFILE_ 
MODIFY creates the default mail file specification from the following sources: 


¢ Disk and directory defined in the caller’s user authorization file (UAF) 

e Subdirectory defined in the Mail user profile 

e Default file type of .MAI 

MAIL$ MAILFILE_NAME 

MAIL$ MAILFILE_NAME specifies the name of the mail file that the Mail 


utility should open. The buffer address field points to a buffer that contains a 
character string of 0 to 255 characters. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If you do not specify MAIL$ MAILFILE_ NAME, the default mail file name is 
MAIL. 


MAIL$ MAILFILE_WASTEBASKET_NAME 
MAILFILE_WASTEBASKET_NAME specifies a new folder name for the 
wastebasket in the specified mail file. The buffer address field points toa 
buffer that contains a character string of 1 to 39 characters. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Code 


MAIL$ MAILFILE_RESULTSPEC 

When you specify MAIL$ MAILFILE_RESULTSPEC, the Mail utility returns the 
resultant mail file specification. The buffer address field points to a buffer that 
receives a character string from 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


If a mail file is not specified, the currently open mail file is used. 
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Mail Utility Routines 
MAIL$MAILFILE_MODIFY 


Condition Values Returned 


MAIL$ ILLFOLNAM The specified folder name is illegal. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOTISAM The message file is not an indexed file. 
MAIL$ OPENIN Mail cannot open the file as input. 
SS$ ACCVIO Access violation. 


Any condition value returned by $CLOSE, $FIND, $PUT, and $UPDATE. 
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Mail Utility Routines 
MAIL$MAILFILE_OPEN 


MAIL$MAILFILE_-OPEN—Open a Mail File for Processing 


Format 


Returns 


Arguments 


Opens a specified mail file for processing. You must use this routine to open a 
mail file before you can do either of the following: 


e Call any mail file routines to manipulate mail files 
* Call message routines to read messages from the specified mail file 


MAIL$MAILFILE_ OPEN context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$ MAILFILE_DEFAULT_NAME 

MAIL$ MAILFILE_DEFAULT_NAME specifies the default file specification 
MAIL$MAILFILE_OPEN should use when opening a mail file. The buffer 
address field points to a character string of 0 to 255 characters that defines the 
default file specification. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Mail Utility Routines 
MAIL$MAILFILE_OPEN 


Output Item 


If you specify the value 0 in the buffer length field of the item descriptor, 
MAIL$MAILFILE_OPEN uses the current default directory as the default mail 
file specification. 


If you do not specify MAIL$ MAILFILE_DEFAULT_ NAME, MAIL$MAILFILE_ 
OPEN creates the default mail file specification from the following sources: 


¢« Disk and directory defined in the caller’s user authorization file (UAF) 

e Subdirectory defined in the Mail user profile 

e Default file type of .MAI 

MAIL$_MAILFILE_NAME 

MAIL$ MAILFILE_NAME specifies the name of the mail file MAIL$MAILFILE_ 


OPEN should open. The buffer address field points to a buffer that contains a 
character string of 0 to 255 characters. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
If you do not MAIL$ MAILFILE_NAME, the default mail file name is MAIL. 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$ MAILFILE DELETED BYTES 

When you specify MAIL$ MAILFILE_ DELETED BYTES, MAIL$MAILFILE_ 
OPEN returns the number of deleted bytes in the specified mail file as a longword 
value. 


MAIL$_MAILFILE_INDEXED 

When you specify MAIL$ MAILFILE_INDEXED, MAIL$MAILFILE_OPEN 
returns a Boolean TRUE when you open an indexed file. The buffer length field 
points to a longword that receives the Boolean value. 


MAIL$ MAILFILE_RESULTSPEC 

When you specify MAIL$ MAILFILE_RESULTSPEC, MAIL$MAILFILE_OPEN 
returns the resultant mail file specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string O to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ MAILFILE_WASTEBASKET 

When you specify MAIL$ MAILFILE_WASTEBASKET, MAIL$MAILFILE_OPEN 
returns the name of the wastebasket for the specified mail file. The buffer 
address field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Mail Utility Routines 
MAIL$MAILFILE_OPEN 


Description 
The default mail file specification is MAIL.MAI in the MAIL subdirectory. 


Condition Values Returned 


MAIL$ FILEOPEN The mail file is already open. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 
MAIL$ NOMSGS No messages are available. 

SS$ ACCVIO Access violation. 


Any condition value returned by LIB$GET_VM, $CONNECT, and $OPEN. 
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Mail Utility Routines 
MAIL$MAILFILE_PURGE_WASTE 


MAIL$MAILFILE_PURGE_WASTE—Delete Wastebasket Messages 


Deletes messages contained in the wastebasket folder of the currently open mail 


file. 
Format 
MAIL$MAILFILE_.PURGE_WASTE context ,in_item_list ,out_item_list 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


Mail file context information to be passed to other mail file routines. The context 
argument is the address of a longword that contains mail file context information. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MAILFILE_RECLAIM 

The Boolean item code MAIL$ MAILFILE_RECLAIM specifies that 
MAIL$MAILFILE_PURGE_WASTE purge the wastebasket folder and reclaim 
deleted space in the mail file. 


Specify the value 0 in the buffer length field of the item descriptor. 


MAIL$ MAILFILE RECLAIM explicitly requests a reclaim operation and 
overrides the deleted byte's threshold regardless of the number of bytes deleted 
during a mail file purge operation. 
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Output Item 


Description 


Mail Utility Routines 
MAIL$MAILFILE_PURGE_WASTE 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$ MAILFILE_DATA_RECLAIM 

When you specify MAIL$ MAILFILE_DATA_ RECLAIM, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of data buckets reclaimed during the 
reclaim operation as a longword value. 


MAIL$ MAILFILE_DATA_SCAN 

When you specify MAIL$ MAILFILE_DATA_SCAN, MAIL$MAILFILE_PURGE_ 
WASTE returns the number of data buckets scanned during the reclaim operation 
as a longword value. 


MAIL$ MAILFILE_INDEX_RECLAIM 

When you specify MAIL$ MAILFILE_INDEX_RECLAIM, the Mail utility returns 
the number of index buckets reclaimed during a reclaim operation as a longword 
value. 


MAIL$_MAILFILE_DELETED_BYTES 

When you specify MAIL$ MAILFILE DELETED BYTES, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of bytes deleted from the mail file as a 
longword value. 


MAIL$_MAILFILE_MESSAGES DELETED 

When you specify MAIL$ MAILFILE_MESSAGES DELETED, 
MAIL$MAILFILE_PURGE_WASTE returns the number of deleted messages 
as a longword value. 


MAIL$ MAILFILE_TOTAL_RECLAIM 

When you specify MAIL$ MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of bytes reclaimed due to a reclaim 
operation as a longword value. 


If you specify the MAIL$ MAILFILE_ RECLAIM item descriptor, all the bytes 
deleted from the mail file by this routine are reclaimed. 
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Mail Utility Routines 
MAIL$MAILFILE_PURGE_WASTE 


Condition Values Returned 


MAIL$ NORMAL 
MAIL$ INVITMCOD 
MAIL$_INVITMLEN 
MAIL$ MISREQITEM 
MAIL$ NOFILEOPEN 
MAIL$ NOTISAM 
SS$ ACCVIO 
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Normal successful completion. 

The specified item code is invalid. 

The specified item length is invalid. 
The required item is missing. 

No mail file is currently open. 

The message file is not an indexed file. 
Access violation. 


Mail Utility Routines 
MAIL$MESSAGE_BEGIN 


MAIL$MESSAGE_BEGIN—Start Message Processing 


Format 


Returns 


Arguments 


Begins message processing. You must call this routine before calling any other 
message routines. 


MAIL$MESSAGE_BEGIN context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to various message routines. The 
context argument is the address of a longword that contains message context 
information. 


You should specify the value of this argument as 0 in the first of a sequence of 
calls to message routines. In the following calls, you should specify the message 
context value returned by this routine. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$ MESSAGE _FILE_CTX 

MAIL$ MESSAGE_FILE_CTX specifies the mail file context received from 
MAIL$MAILFILE_BEGIN to be passed to the message routines. The buffer 
address field of the item descriptor points to a longword that contains mail file 
context information. 


The item code MAIL$ MESSAGE _FILE_CTX is required. 
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Mail Utility Routines 
MAIL$MESSAGE_BEGIN 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Output Item Code 


MAIL$_MESSAGE_SELECTED 
When you specify MAIL$ MESSAGE SELECTED, MAIL$MESSAGE_ BEGIN 
returns the number of messages selected as a longword value. 

Description 
MAIL$MESSAGE_BEGIN creates and initializes a message context for 
subsequent calls to message routines. 


Condition Values Returned 


MAIL$ ILLCTXADR The context block address is illegal. 
MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOFILEOPEN The mail file is not open. 

MAIL$ WRONGCTX The context block is incorrect. 

MAIL$ WRONGFILE The specified file is incorrect in this context. 
SS$ ACCVIO Access violation. 


Any condition value returned by $GET and LIB$GET_VM. 


MAIL-54 = Mail Utility (MAIL) Routines 


Mail Utility Routines 
MAIL$MESSAGE_COPY 


MAIL$MESSAGE_COPY—Copy Messages to Another File or Folder 


Format 


Returns 


Arguments 


Copies messages between files or folders. 


MAIL$MESSAGE_COPY context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 


You should specify this argument as 0 in the first of a sequence of calls to 
message routines. In the following calls, you should specify the message context 
value returned by the previous routine. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$ MESSAGE_BACK 
When you specify the Boolean item code MAIL$ MESSAGE _ BACK, 
MAIL$MESSAGE_COPY copies the message preceding the current message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ID, and MAIL$_ 
MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY. 
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Mail Utility Routines 
MAIL$MESSAGE_COPY 


MAIL$_MESSAGE_DEFAULT_NAME 

MAIL$ MESSAGE _DEFAULT_NAME specifies the default file specification of a 
mail file to open in order to copy a message. The buffer address field of the item 
descriptor points to a buffer that contains a character string O to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_MESSAGE_DELETE 
When you specify the Boolean item code MAIL$ MESSAGE DELETE, 


MAIL$MESSAGE_COPY deletes the message in the current folder after the 
message has been copied to a destination folder. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Specify MAIL$ MESSAGE DELETE to emulate the operation of MAIL MOVE or 
FILE command. 


MAIL$_MESSAGE_FILE_ACTION 
MAIL$ MESSAGE_FILE_ACTION specifies the address of the mail file action 
routine called if a mail file is to be created. Two parameters are passed as follows: 


e User data longword 
e Address of the descriptor of the file name to be created 


The buffer address field of the item descriptor points to a longword that denotes 
a procedure value. 


MAIL$_MESSAGE_FILENAME 

MAIL$ MESSAGE_FILENAME specifies the name of the mail file to which the 
current message will be moved. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$ MESSAGE_FOLDER 
MAIL$ MESSAGE FOLDER specifies the name of the target folder for moving 


mail messages. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
The item code MAIL$ MESSAGE _ FOLDER is required. 

MAIL$_ MESSAGE_FOLDER_ACTION 

MAIL$ MESSAGE_FOLDER_ACTION specifies the entry point address of the 


folder action routine called if a folder is to be created. Two parameters are passed 
as follows: 


e User data longword 
e Address of a descriptor of the folder name to be created. 


The buffer address field of the item descriptor points to a longword that 
specifies a procedure value. 
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Output Item 


Mail Utility Routines 
MAIL$MESSAGE_COPY 


MAIL$ MESSAGE _ID 

MAIL$ MESSAGE _ID specifies the message identification number of the message 
on which the operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 


Do not specify MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ID, and MAIL$_ 
MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY. 


MAIL$_MESSAGE_NEXT 
When you specify the Boolean item code MAIL$ MESSAGE NEXT, the Mail 
utility copies the message following the current message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ID, and MAIL$_ 
MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY. 


MAIL$ MESSAGE_USER_DATA 

MAIL$ MESSAGE_USER_DATA specifies data passed to the folder action and 
mail file action routines. The buffer address field of the item descriptor points 
to a user data longword. 


Specify MAIL$ MESSAGE_USER_DATA with the item codes MAIL$ MESSAGE __ 
FILE ACTION and MAIL$ MESSAGE_FOLDER ACTION only. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$_MESSAGE_FILE_CREATED 

When you specify the Boolean item code MAIL$ MESSAGE _FILE_CREATED, 
MAIL$MESSAGE_COPY returns the value of the file created flag as longword 
value. 


MAIL$_MESSAGE_FOLDER_CREATED 

When you specify the Boolean item code MAIL$ MESSAGE FOLDER_ 
CREATED, MAIL$MESSAGE_COPY returns the value of the folder created 
flag as a longword value. 


MAIL$_ MESSAGE_RESULTSPEC 

When you specify MAIL$ MESSAGE RESULTSPEC, MAIL$MESSAGE_COPY 
returns the mail file resultant file specification. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$MESSAGE_COPY 


Description 


If you do not specify a file name, the routine copies the message to another folder 
in the currently open mail file. The target mail file must be an indexed file. 


Condition Values Returned 


SS$ NORMAL 
MAIL$ BADVALUE 
MAIL$ CONITMCOD 


MAIL$ DATIMUSED 


MAIL$ DELMSG 
MAIL$ ILLCTXADR 
MAIL$_INVITMCOD 
MAIL$_ INVITMLEN 
MAIL$ MISREQITEM 
MAIL$ MSGINFO 
MAIL$ MSGTEXT 
MAIL$ NOFILEOPEN 
MAIL$ NOMOREREC 
MAIL$ NOTREADIN 


MAIL$ RECTOBIG 
MAIL$ WRONGCTX 
MAIL$ WRONGFILE 
SS$_IVDEVNAM 
SS$ ACCVIO 


Normal successful completion. 
The specified keyword value is invalid. 


The specified item codes define conflicting 
operations. 


The date and time is currently used in the 
specified file. 

The message is deleted. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 
Informational records are successfully returned. 
Text record is successfully returned. 

The mail file is not open. 

No more records can be found. 


The operation is invalid; you are not reading a 
message. 


The record is too large for the MAIL buffer. 
The context block is incorrect. 

The specified file is incorrect in this context. 
The device name is invalid. 

Access violation. 


Any condition value returned by $CONNECT, $CREATE, $OPEN, $WRITE, 


$READ, and $PUT. 
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Mail Utility Routines 
MAIL$MESSAGE_DELETE 


MAIL$MESSAGE_DELETE—Delete Message From Current Folder 


Format 


Returns 


Arguments 


Deletes a specified message from the currently selected folder. 


MAIL$MESSAGE_DELETE context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$ MESSAGE _ID 

MAIL$ MESSAGE _ID specifies the message identification number of the message 
on which the operation is to be performed. The buffer address field points toa 
longword that contains the message identification number. 


The item code MAIL$ MESSAGE ID is required. 
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out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 

describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Output Item Codes 


None. 


Description 


When you delete a message from a selected folder, it is moved to the wastebasket 
folder. You cannot delete a message from the wastebasket folder. You must use 
the MAIL$MAILFILE_PURGE_WASTE routine to empty the wastebasket folder. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

MAIL$ ILLCTXADR The context block address is illegal. 
MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOFILEOPEN The mail file is not open. 

MAIL$ WRONGCTX The context block is incorrect. 

MAIL$ WRONGFILE The specified file is incorrect in this context. 
SS$ ACCVIO Access violation. 
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MAIL$MESSAGE_END—End Message Processing 


Format 


Returns 


Arguments 


Description 


Ends message processing. 


MAIL$MESSAGE_END context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_ BEGIN. If message processing ends successfully, 
the argument context is changed to 0. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. This routine does not use the in_ 
item_list argument. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. This routine 
does not use the out_item_list argument. 


The MAIL$MESSAGE_END routine deallocates the message context created by 
MAIL$MESSAGE _ BEGIN as well as any dynamic memory allocated by other 
message routines. 
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Condition Values Returned 


MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition value returned by LIB$FREE_ VM. 
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MAIL$MESSAGE_GET—Get Message From a Set of Messages 


Format 


Returns 


Arguments 


Retrieves a message from the set of currently selected messages. 


MAIL$MESSAGE_GET context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_ BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MESSAGE_AUTO_NEWMAIL 

When you specify the Boolean item code MAIL$ MESSAGE_AUTO_NEWMAIL, 
MAIL$MESSAGE_GET automatically places a new message in the mail folder 
as it is read. MAIL$ MESSAGE AUTO NEWMAIL is valid only when specified 
with the item code MAIL$ MESSAGE_CONTINUE. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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MAIL$_MESSAGE_BACK 

When you specify the Boolean item code MAIL$ MESSAGE _ BACK, 
MAIL$MESSAGE_GET reads the message identification number of a specified 
message to return the first record of the preceding message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify the item codes MAIL$ MESSAGE _ BACK, MAIL$ MESSAGE _ 
CONTINUE, MAIL$ MESSAGE _ID, and MAIL$ MESSAGE_NEXT in the same 
call to MAIL$MESSAGE_GET. 


MAIL$_MESSAGE_CONTINUE 

When you specify the Boolean item code MAIL$ MESSAGE CONTINUE, 
MAIL$MESSAGE_ GET reads the message identification number of a specified 
message to return the next text record of the current message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify the item codes MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ 
CONTINUE, MAIL$ MESSAGE ID, and MAIL$ MESSAGE NEXT in the same 
call to MAIL$MESSAGE_GET. 


MAIL$ MESSAGE_ID 

MAIL$ MESSAGE _ID specifies the message identification number of a message 
on which an operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 


Do not specify the item codes MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ 
CONTINUE, MAIL$ MESSAGE ID, and MAIL$ MESSAGE NEXT in the same 
call to MAIL$MESSAGE_ GET. 


MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$ MESSAGE _ NEXT, 
MAIL$MESSAGE_GET reads the message identification number of a specified 
message to return the first record of the message following the current message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify the item codes MAIL$ MESSAGE _ BACK, MAIL$ MESSAGE _ 
CONTINUE, MAIL$ MESSAGE ID, and MAIL$ MESSAGE NEXT in the same 
call to MAIL$MESSAGE_GET. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 
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Output Item Codes 


MAIL$_MESSAGE_BINARY_DATE 
When you specify MAIL$ MESSAGE _BINARY_DATE, MAIL$MESSAGE_GET 
returns the message arrival date as a quadword binary value. 


MAIL$ MESSAGE_CC 

When you specify MAIL$ MESSAGE CC, MAIL$MESSAGE _ GET returns the 
CC: field of the current message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_ MESSAGE_CURRENT_ID 

When you specify MAIL$ MESSAGE CURRENT_ID, MAIL$MESSAGE_GET 
returns the message identification number of the current message. The buffer 
address field of the item descriptor points to a longword that receives the 
message identifier number. 


MAIL$_MESSAGE_DATE 

When you specify MAIL$ MESSAGE DATE, MAIL$MESSAGE _GET returns the 
message creation date string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_MESSAGE_EXTID 
MAIL$ MESSAGE_EXTID specifies the external message identification number 


of the current message. The buffer address field of the item descriptor points to 
a buffer that contains a character string 0 to 255 characters long. 


MAIL$ MESSAGE_FROM 

When you specify MAIL$ MESSAGE FROM, MAIL$MESSAGE GET returns 
the From: field of the specified message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_ MESSAGE_RECORD 

When you specify MAIL$¢ MESSAGE RECORD, MAIL$MESSAGE_GET returns 
a record of the message. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ MESSAGE_RECORD is valid only when specified with the item code 
MAIL$ MESSAGE_CONTINUE. 


Do not specify MAIL$ MESSAGE RECORD with the following item codes: 
e MAIL$ MESSAGE BACK 

e MAIL$ MESSAGE ID 

e MAIL$ MESSAGE NEXT 
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Description 


MAIL$_MESSAGE_RECORD_TYPE 

When you specify MAIL$¢ MESSAGE _RECORD_TYPE, MAIL$MESSAGE_GET 
returns the record type. A record may be either header information (MAIL $_ 
MESSAGE HEADER) or text (MAIL$ MESSAGE_TEXT). The buffer address 
field of the item descriptor points to a word that receives the record type. 


MAIL$_MESSAGE_RETURN_FLAGS 
When you specify MAIL$ MESSAGE _RETURN_FLAGS, MAIL$MESSAGE_GET 
returns the Mail system flag for the current message as a 2-byte bit mask value. 


MAIL$_MESSAGE_SENDER 

When you specify MAIL$ MESSAGE SENDER, MAIL$MESSAGE_ GET returns 
the name of the sender of the current message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_SIZE 
When you specify MAIL$ MESSAGE_SIZE, MAIL$MESSAGE GET returns the 
size in records of the current message as a longword value. 


MAIL$ MESSAGE SUBJECT 

When you specify MAIL$ MESSAGE SUBJ ECT, MAIL$MESSAGE_GET returns 
the Subject: field of the specified message. The buffer address field of the item 
descriptor points to a buffer that receives a character string O to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_TO 

When you specify MAIL$ MESSAGE TO, MAIL$MESSAGE_ GET returns the To: 
field of the specified message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The first time the MAIL$MESSAGE_GET routine is called, the message 
information is returned for the first requested message, and the status returned 
is MAIL$ MSGINFO. Subsequent calls to MAIL$¢MESSAGE_GET with the 
MAIL$ MESSAGE_CONTINUE item code return the message text records with 
the status MAIL$ MSGTEXT, until no more records are left, when MAIL $_ 
NOMOREREC is returned. 


Condition Values Returned 


MAIL$ MSGINFO Informational records are successfully returned. 
MAIL$ MSGTE XT Text record is successfully returned. 

MAIL$ ILLCTXADR The context block address is illegal. 

MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 
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MAIL$ NOFILEOPEN 
MAIL$ NOMOREREC 
MAIL$ NOTREADIN 


MAIL$ RECTOBIG 
MAIL$ WRONGCTX 
MAIL$ WRONGFILE 
SS$ ACCVIO 
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The mail file is not open. 
No more records can be found. 


The operation is invalid; you are not reading a 
message. 


The record is too large for the mail buffer. 
The context block is incorrect. 

The specified file is incorrect in this context. 
Access violation. 


Any condition value returned by $FIND and $UPDATE. 
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MAIL$MESSAGE_INFO—Get Information About a Message 


Obtains information about a specified message contained in the set of currently 
selected messages. 


Format 
MAIL$MESSAGE_INFO_ context ,in_item_list ,out_item_list 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$¢MESSAGE_BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MESSAGE_BACK 

When you specify Boolean item code MAIL$ MESSAGE BACK, 
MAIL$MESSAGE_INFO reads the identification number of the current message 
and returns the preceding message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify MAIL$ MESSAGE _BACK, MAIL$ MESSAGE_ID, and MAIL$_ 
MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO. 
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MAIL$ MESSAGE _ID 

MAIL$ MESSAGE _ID specifies the message identification number of the message 
on which the operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 


Do not specify MAIL$ MESSAGE_BACK, MAIL$ MESSAGE _ID, and MAIL$_ 
MESSAGE _NEXT in the same call to MAIL$MESSAGE_INFO. 


MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$ MESSAGE NEXT, 
MAIL$MESSAGE_INFO reads the message identification number of the current 
message and returns the message that follows it. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ID, and MAIL$_ 
MESSAGE _NEXT in the same call to MAIL$MESSAGE_INFO. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$_MESSAGE_BINARY_DATE 
When you specify MAIL$ MESSAGE BINARY DATE, MAIL$MESSAGE_INFO 
returns the message arrival date as a quadword binary value. 


MAIL$ MESSAGE_CC 

When you specify MAIL$ MESSAGE CC, MAIL$MESSAGE_INFO returns the 
CC: field of the current message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ MESSAGE_CURRENT_ID 

When you specify MAIL$¢ MESSAGE _ID, MAIL$MESSAGE_INFO returns the 
message identification number of the current message. The buffer address 
field of the item descriptor points to a longword that receives the message 
identification number of the current message. 


MAIL$_MESSAGE_DATE 

When you specify MAIL$ MESSAGE DATE, MAIL$MESSAGE_INFO returns 
the message creation date string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$ MESSAGE_EXTID 

When you specify MAIL$ MESSAGE EXTID, MAIL$MESSAGE_INFO returns 
the external identification number of the current message as a string. The buffer 
address field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_FROM 

When you specify MAIL$ MESSAGE FROM, MAIL$MESSAGE_INFO returns 
the From: field of the specified message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_REPLY_PATH 

When you specify MAIL$ MESSAGE _REPLY_PATH, MAIL$MESSAGE_INFO 
returns the reply path of the specified message. The buffer address field of 

the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ MESSAGE_RETURN_FLAGS 

When you specify MAIL$ MESSAGE RETURN FLAGS, MAIL$MESSAGE _ 
INFO returns the Mail system flag values for the current message as a 2-byte bit 
mask value. 


MAIL$_MESSAGE_SENDER 

When you specify MAIL$ MESSAGE SENDER, MAIL$MESSAGE_INFO returns 
the name of the sender of the current message. The buffer address field of 

the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_SIZE 
When you specify MAIL$ MESSAGE_ SIZE, MAIL$MESSAGE _INFO returns the 
size of the current message in records as a longword value. 


MAIL$ MESSAGE SUBJECT 

When you specify MAIL$ MESSAGE SUBJ ECT, MAIL$MESSAGE_INFO 
returns the Subject: field of the specified message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_MESSAGE_TO 
When you specify MAIL$¢ MESSAGE _TO, MAIL$MESSAGE_INFO returns the 


To: field of the specified message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$MESSAGE_INFO obtains information about a particular message. 
MAIL$MESSAGE _ GET retrieves a message from the set of currently selected 


messages. 


The first call to MAIL$¢MESSAGE_GET passes control to MAIL$MESSAGE _ 
INFO. Subsequent calls that include the MAIL$ MESSAGE CONTINUE item 


code return text records. 


Condition Values Returned 


MAIL$ CONITMCOD 


MAIL$ DELMSG 
MAIL$ ILLCTXADR 
MAIL$ INVITMCOD 
MAIL$_INVITMLEN 
MAIL$ MISREQITEM 
MAIL$ NOFILEOPEN 
MAIL$ NOMOREMSG 
MAIL$ WRONGCTX 
MAIL$ WRONGFILE 
SS$ ACCVIO 


The specified item codes define conflicting 
operations. 


The message is deleted. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The mail file is not open. 

No more messages. 

The context block is incorrect. 

The specified file is incorrect in this context. 
Access violation. 


Any condition value returned by LIB$GET_VM. 
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MAIL$MESSAGE_MODIFY—Modify Header Information 


Format 


Returns 


Arguments 


Modifies information in the message header. 


MAIL$MESSAGE_MODIFY context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_MESSAGE_BACK 

When you specify the Boolean item code MAIL$ MESSAGE BACK, 
MAIL$MESSAGE_MODIFY reads the identification number of the specified 
message in order to return the first record in the preceding message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify the item codes MAIL$ MESSAGE_BACK, MAIL$ MESSAGE _ID, 
and MAIL$ MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY. 
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MAIL$ MESSAGE_FLAGS 

MAIL$ MESSAGE_FLAGS specifies system flags for new mail. The buffer 
address field of the item descriptor points to a word that contains bit mask 
offsets. The following offsets can be used to modify the 2-byte bit mask: 


e MAIL$V_replied 
e MAIL$V_marked 


MAIL$ MESSAGE_ID 

MAIL$ MESSAGE _ID specifies the message identification number of the message 
on which an operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 


Do not specify the item codes MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ID, 
and MAIL$ MESSAGE NEXT in the same call to MAIL$MESSAGE_ MODIFY. 


MAIL$_ MESSAGE_NEXT 

When you specify the Boolean item code MAIL$ MESSAGE _NEXT, 
MAIL$MESSAGE_MODIFY reads the message identification number of a 
message and returns the first record in the message following the current 
message. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify the item codes MAIL$ MESSAGE BACK, MAIL$ MESSAGE _ID, 
and MAIL$ MESSAGE_NEXT in the same call toMAIL$MESSAGE_ MODIFY. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 

describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Code 


MAIL$_ MESSAGE_CURRENT_ID 

When you specify MAIL$¢ MESSAGE_CURRENT_ID, MAIL$MESSAGE_ 
MODIFY returns the message identification number of the current message. 
The buffer address field of the item descriptor points to a longword that 
receives the message identification number. 


Condition Values Returned 


MAIL$ CONITMCOD The specified item codes define conflicting 
operations. 

MAIL$ DELMSG The message is deleted. 

MAIL$ ILLCTXADR The context block address is illegal. 

MAIL$ INVITMCOD The specified item code is invalid. 
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MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOFILEOPEN The mail file is not open. 

MAIL$ NOMOREMSG No more messages. 

MAIL$ WRONGCTX The context block is incorrect. 

MAIL$ WRONGFILE The specified file is incorrect in this context. 
SS$ ACCVIO Access violation. 


Any condition value returned by $FIND and $UPDATE. 
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MAIL$MESSAGE_SELECT—Select Message from Current Mail File 


Format 


Returns 


Arguments 


Selects a message or messages from the currently open mail file. Before you 
attempt to read a message, you must select it. 


MAIL$MESSAGE_SELECT context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$ MESSAGE _ BEFORE 

When you specify MAIL$ MESSAGE BEFORE, MAIL$MESSAGE_ SELECT 
selects a message received before a specified date and time. The buffer address 
field of the item descriptor points to a buffer that contains a character string 0 to 
255 characters long in absolute time. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$ MESSAGE_CC_ SUBSTRING 

MAIL$ MESSAGE _CC_ SUBSTRING specifies a character string that must 
match a substring contained in the CC: field of the specified message. If the 
strings match, the message is selected. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_FLAGS 
MAIL$ MESSAGE_FLAGS specifies bit masks that must be initialized to 1. 


MAIL$_MESSAGE_FLAGS MBZ 
MAIL$ MESSAGE FLAGS MBZ specifies Mail system flags that must be set to 
0. 


MAIL$_MESSAGE_FOLDER 
MAIL$ MESSAGE_FOLDER specifies the name of the folder that contains 
messages to be selected. 


The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
This item code is required. 


MAIL$_MESSAGE_FROM_SUBSTRING 

MAIL$ MESSAGE _FROM_SUBSTRING specifies a user-specified character 
string that must match the substring contained in the From: field of a specified 
message. If the strings match, the message is selected. 


The buffer address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_SINCE 
When you specify MAIL$ MESSAGE_SINCE, the Mail utility selects a message 
received on or after a specified date and time. 


The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long in absolute time. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_MESSAGE_TO_SUBSTRING 

MAIL$ MESSAGE _TO SUBSTRING Specifies a user-specified character string 
that must match a substring contained in the To: field of a specified message. If 
the strings match, the message is selected. 


The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_MESSAGE_SUBJ_SUBSTRING 
MAIL$ MESSAGE_SUBJ SUBSTRING specifies a user-specified character 


string that must match a substring contained in the Subject: field of a specified 
message. If the strings match, the message is selected. 


MAIL-76 Mail Utility (MAIL) Routines 


Output Item 


Description 
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The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Code 


MAIL$_ MESSAGE_SELECTED 
When you specify MAIL$ MESSAGE SELECTED, MAIL$MESSAGE_ SELECT 
returns the number of selected messages as a longword value. 


MAIL$MESSAGE_ SELECT deselects previously selected messages whether or 
not you request a valid selection. 


Condition Values Returned 


MAIL$ ILLCTXADR The context block address is illegal. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ INVQUAVAL The specified qualifier is invalid 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOFILEOPEN The mail file is not open. 

MAIL$ NOTEXIST The specified folder does not exist. 
MAIL$ NOTISAM The operation applies only to indexed files. 
MAIL$ WRONGCTX The context block is incorrect. 

MAIL$ WRONGFILE The specified file is incorrect in this context. 
SS$ ACCVIO Access violation. 


Any condition value returned by LIB$GET_VM. 
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MAIL$SEND_ABORT—Cancel Send Operation 


Format 


Returns 


Arguments 


Cancels a currently executing send operation. 


MAIL$SEND_ABORT context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Value Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine This routine does not use the in_ 
item_list argument. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. This routine 
does not use the out_item_list argument. 
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Description 


MAIL$SEND_ABORT is useful when, for example, the user presses Ctrl/C during 
the execution of MAIL$SEND_MESSSAGE. 


Condition Value Returned 


SS$ NORMAL Normal successful completion. 
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MAIL$SEND_ADD_ADDRESS—Add Address to List 


Adds an address to the address list. If an address list does not exist, 
MAIL$SEND_ADD_ ADDRESS creates one 


Format 
MAIL$SEND_ADD_ ADDRESS context ,in_item_list ,out_item_list 


Returns 


OpenVMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_ BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_SEND_ USERNAME 

MAIL$ SEND_USERNAME specifies that the Mail utility add a specified user 
name to the address list. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
The item code MAIL$¢ SEND_USERNAME is required. 
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Output Item 


Description 
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MAIL$_SEND_USERNAME_TYPE 

MAIL$ SEND_USERNAME_TYPE specifies the type of user name added to the 
address list. The buffer address field of the item descriptor points to a word 
that contains the user name type. 


There are two types of user names, as follows: 
e User name specified as a To: address (default) 


e User name specified as a CC: address 


Note 


Currently, the symbols MAIL$ TO and MAIL$ CC define user name 
types. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


None. 


If you do not specify a MAIL$¢ SEND_ USERNAME _TYPE, MAIL$SEND_ADD_ 
ADDRESS uses MAIL$ TO. You can specify only one user name per call to 
MAIL$SEND_ADD_ ADDRESS. 


Condition Values Returned 


MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition values returned by LIB$TPARSE. 
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MAIL$SEND_ADD_ATTRIBUTE—Add Attribute to the Current 
Message 


Adds an attribute, such as Subject or To, to the message you are currently 
constructing. 


Format 
MAIL$SEND_ADD_ATTRIBUTE context ,in_item_list ,out_item_list 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 


You should specify this argument as 0 in the first of a sequence of calls to MAIL 
routines. In following calls, you should specify the Send context value returned 
by the previous routine. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_SEND_CC_LINE 

MAIL$ SEND_CC_LINE specifies a descriptor of the CC: field text. The buffer 
address field of the item descriptor points to a buffer that contains a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Output Item 


Description 
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MAIL$_SEND_FROM_LINE 

MAIL$ SEND_FROM_LINE specifies a descriptor of the From: field text of the 
message to be sent. The buffer address field of the item descriptor points toa 
buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Calls to MAIL$SEND_ADD_ATTRIBUTE using this input item code should be 
made before any calls to MAIL$SEND_ADD_ADDRESS. 


The SYSPRV privilege is required to alter the From: of a message. 


MAIL$ SEND SUBJECT 

MAIL$ SEND SUBJ ECT specifies a descriptor of the Subject: field text of a 
message to be sent. The buffer address field of the item descriptor points toa 
buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ SEND TO_LINE 

MAIL$ SEND_TO_LINE specifies a descriptor of the To: field text of the 
message. The buffer address field of the item descriptor points to a buffer 
that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


None. 


If you do not specify a To: line, the Mail utility supplies a To: line composed of 
user names on the To: address list. If you do not specify a CC: line, the Mail 
utility supplies a CC: line composed of user names on the CC: address list. In 
either of the above cases, commas separate the user names. 


To add a message's From: field, you must have the SYSPRV privilege, and the 
Mail DECnet object must have the SYSPRV privilege on OUTGOING CONNECT 
(users can set the DECnet object privileges at their discretion). 
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Condition Values Returned 


SS$ NORMAL 
MAIL$ INVITMCOD 
MAIL$ INVITMLEN 
MAIL$ MISREQITEM 
SS$ ACCVIO 
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Normal successful completion. 

The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 
Access violation. 
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MAIL$SEND_ADD_BODYPART—Build Message Body 


Format 


Returns 


Arguments 


Builds the body of a message. 


MAIL$SEND_ADD_ BODYPART context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 
See MAIL$SEND_BEGIN for a description of an input item descriptor. 


Input Item Codes 


MAIL$_SEND_DEFAULT_NAME 

MAIL$ SEND_DEFAULT_NAME specifies the default file specification of a text 
file to be opened. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_SEND_FID 
MAIL$ SEND_FID specifies the file identifier of the text file to be opened. The 


buffer address field of the item descriptor points to a buffer that contains the 
file identifier. To identify a file using a file identifier, you must also specify the 
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Output Item 


device identifier for the file. Specify the device identifier using the MAIL$_ 
SEND_DEFAULT_NAME item code. More information about using a file ID for 
specifying files can be found in OpenVMS Record Management Services Reference 
Manual. Note that the MAIL$ SEND_FID item code and the MAIL$ SEND_ 
FILENAME item code are mutually exclusive. 


MAIL$_SEND_FILENAME 

MAIL$ SEND FILENAME specifies the input file specification of the text file 

to be opened. The buffer address field of the item descriptor points to a buffer 
that receives a character string 0 to 255 characters long. Note that the MAIL$_ 
SEND_FILENAME item code and the MAIL$ SEND _FID item code are mutually 
exclusive. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_SEND_ RECORD 
MAIL$ SEND_RECORD specifies a descriptor of a text record to be added to the 


body of the message. The buffer address field of the item descriptor points toa 
buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


When creating a message, do not specify MAIL$ SEND_RECORD in the same 
call (or series of calls) to MAIL$SEND_ADD_BODYPART with the following item 
codes: 


* MAIL$ SEND FID 
* MAIL$ SEND FILENAME 


Note 


Do not use the MAIL$ SEND _RECORD item code with the MAIL$SEND_ 
ADD_BODYPART routine called from a detached process. The routine 
creates a temporary file in SYS$SCRATCH that is inaccessible to the 
detached process. 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Code 


MAIL$_SEND_RESULTSPEC 

When you specify MAIL$ SEND _RESULTSPEC, MAIL$SEND_ADD_BODYPART 
returns the resultant file specification identified with MAIL$ SEND_FILENAME. 
The buffer address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Description 


You can use MAIL$SEND_ADD_ BODY PART to specify a file that contains the 
entire message or to add a single record to a message. If the message is contained 
in a file, you call MAIL$¢SEND_ADD_BODYPART once, specifying the file name. 
If you want to add to the message record-by-record, you can call MAIL$SEND_ 
ADD_BODYPART repeatedly, specifying a different record each time until you 
complete the message. 


You cannot specify both a file name and a record for the same message. You can 
specify either MAIL$ SEND_FILENAME or MAIL$ SEND FID once, or you can 
specify MAIL$¢ SEND RECORD oneor more times. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

MAIL$ CONITMCOD The specified item codes define conflicting 
operations. 

MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ OPENIN The required file is missing. 

SS$ ACCVIO Access violation. 
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MAIL$SEND_BEGIN—Start Sending Message 


Format 


Returns 


Arguments 


Initiates processing to send a message to the users on the address list. You must 
call MAIL$SEND_BEGIN before you call any other send routine. 


MAIL$SEND_BEGIN context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Send context information to be passed to other send routines. The context 
argument is the address of a longword that contains send context information. 


You should specify the value of this argument as 0 in the first of a sequence of 
calls to send routines. In subsequent calls, you should specify the send context 
value returned by this routine. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_SEND_PERS_NAME 

MAIL$_SEND_NO PERS NAME 

Note that you must specify only one of these item codes. An error is generated if 
you specify both item codes. MAIL$ SEND _PERS NAME specifies the personal 
name text to be used in the message header. The buffer address field of the 
item descriptor points to a buffer that contains a character string 0 to 127 
characters long. 


Specify a value from 0 to 127 in the buffer length field of the item descriptor. 
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The Boolean item code MAIL$ SEND_NO PERS NAME specifies that no 
personal name string be used during message construction. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ SEND_SIGFILE 

MAIL$ SEND _NO_SIGFILE 

Note that you must specify only one of these item codes. An error is generated if 
you specify both item codes. MAIL$ SEND _SIGFILE specifies the full OpenVMS 
file specification of the signature file to be used in the message. The default file 
specification used for a signature file is the user mail directory specification and 
.SIG as the file type. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ SEND _NO_SIGFILE specifies that no signature 
file be used during message construction. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$_SEND_COPY_FORWARD 

When you specify the Boolean item code MAIL$ SEND_COPY_FORWARD, 
MAIL$SEND_BEGIN returns the value of the caller’s copy forward flag as a 
longword value. 


MAIL$ SEND_COPY_SEND 

When you specify the Boolean item code MAIL$ SEND_COPY_SEND, 
MAIL$SEND_BEGIN returns the value of the caller’s copy send flag as a 
longword value. 


MAIL$_SEND_COPY_REPLY 

When you specify the Boolean item code MAIL$ SEND_COPY_REPLY, 
MAIL$SEND_BEGIN returns the value of the caller’s copy reply flag as a 
longword value. 


MAIL$ SEND USER 

When you specify MAIL$ SEND_USER, MAIL$SEND_BEGIN returns the 
process owner's user name. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Description 


MAIL$SEND_BEGIN creates and initializes a send context for subsequent calls 
to send routines. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

MAIL$ CODERR Internal system error. 

MAIL$ CONITMCOD The specified item codes perform conflicting 
operations. 

MAIL$ ILLPERNAME The specified personal name string is illegal. 

MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 

Any condition values returned by $GETJ PIW, LIB$FREE_VM, and LIB$GET_ 

VM. 
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MAIL$SEND_END—End Sending Message 


Format 


Returns 


Arguments 


Terminates send processing. 


MAIL$SEND_END context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_ BEGIN. 


If send processing is successfully terminated, the value of the context argument 
is changed to 0. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. This routine does not use the in_ 
item_list argument. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. This routine 
does not use the out_item_list argument. 
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Description 


The MAIL$SEND_END routine deallocates the send context as well as any 
dynamic memory allocated by previous send routine calls. 


Condition Values Returned 


SS$ NORMAL Normal successful completion 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition value returned by LIB$FREE_VM. 
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MAIL$SEND_MESSAGE 


Format 


Returns 


Arguments 


Begins the actual sending of the message after the message has been constructed. 


MAIL$SEND_ MESSAGE context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list is terminated by longword value of 0. 


Input Item Codes 


MAIL$_SEND_ERROR_ENTRY 

MAIL$ SEND _ERROR_ENTRY specifies the longword address of an entry point 
to process errors during a send operation. The descriptor of the recipient that 
failed, the address of the signal array, and the user-specified data are passed as 
input to the routine. Refer to the HP OpenVMS Programming Concepts Manual 
for more information about the signal array and its use by condition-handling 
routines. 


MAIL$_ SEND SUCCESS ENTRY 

MAIL$ SEND_SUCCESS ENTRY specifies the longword address of an entry 
point to process successes during a send operation. The descriptor of the recipient 
that succeeded, the address of the signal array, and the user-specified data 


Mail Utility (MAIL) Routines MAIL-93 


Mail Utility Routines 
MAIL$SEND_ MESSAGE 


Output Item 


Description 


are passed as input to the routine. Refer to the HP OpenVMS Programming 
Concepts Manual for more information about the signal array and its use by 
condition-handling routines. 


MAIL$_SEND_USER_DATA 
MAIL$ SEND_USER_DATA specifies a longword that MAIL$SEND_MESSAGE 
passes to the SEND action routines. 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


None. 


The MAIL$SEND_MESSAGE routine sends a message built with the 
MAIL$SEND_ADD_BODYPART routine to every user on the address list. If 
you have not used MAIL$SEND_ADD_BODYPART to construct a message, 
MAIL$SEND_MESSAGE sends only a message header. 


If MAIL$SEND_MESSAGE encounters errors sending to an addressee, it calls 
the routine specified by MAIL$ SEND_ERROR_ENTRY. Otherwise, it calls the 
routine specified by MAIL$ SEND SUCCESS ENTRY. 


If either routine is not specified, MAIL$SEND_MESSAGE calls no other routines. 


Condition Values Returned 


MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition value returned by $CONNECT. 
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MAIL$USER_BEGIN—Access the User Profile Database 


Format 


Returns 


Arguments 


Initiates access to the Mail common user database. You must call MAIL$USER_ 
BEGIN before you call any other user routines. 


MAIL$USER_BEGIN context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


User context information to be passed to other user routines. The context 
argument is the address of a longword that contains user context information. 


You should specify the value of this argument as 0 in the first of a sequence of 
calls to MAIL routines. In following calls, you should specify the user context 
value returned by the previous routine. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. This routine does not use the in_ 
item_list argument. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 
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Output Item Codes 


MAIL$_USER_AUTO_PURGE 

When you specify the Boolean item code MAIL$ USER_AUTO PURGE, 
MAIL$USER_BEGIN returns the value of the automatic purge mail flag as a 
longword value. 


MAIL$_USER_CAPTIVE 
When you specify the Boolean item code MAIL$ USER_CAPTIVE, MAIL$USER_ 
BEGIN returns the value of the UAF CAPTIVE flag as a longword value. 


MAIL$_USER_CC_PROMPT 

When you specify the Boolean item code MAIL$ USER_CC_ PROMPT, 
MAIL$USER_BEGIN returns the value of the cc prompt flag as a longword 
value. 


MAIL$_USER_COPY_FORWARD 

When you specify the Boolean item code MAIL$ USER_COPY_FORWARD, 
MAIL$USER_BEGIN returns the value of the copy self forward flag as a 
longword value. 


MAIL$_USER_COPY_REPLY 

When you specify the Boolean item code MAIL$ USER_COPY_REPLY, 
MAIL$USER_BEGIN returns the value of the copy self reply flag as a longword 
value. 


MAIL$_USER_COPY_SEND 

When you specify the Boolean item code MAIL$ USER_COPY_SEND, 
MAIL$USER_BEGIN returns the value of the copy self send flag as a longword 
value. 


MAIL$_USER_FORWARDING 

When you specify MAIL$ USER_FORWARDING, MAIL$USER_BEGIN returns 
the forwarding address string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_FORM 

When you specify MAIL$ USER_FORM, MAIL$USER_BEGIN returns the 
default print form string. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_FULL_DIRECTORY 

When you specify MAIL$ USER _FULL_DIRECTORY, MAIL$USER_BEGIN 
returns complete directory path of the MAIL subdirectory. The buffer address 
field of the item descriptor points to a buffer that receives a character string 0 to 
255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
MAIL$_USER_NEW_MESSAGES 
When you specify MAIL$¢ USER_NEW_MESSAGES, MAIL$USER_BEGIN 


returns the new message count. The buffer address field of the item descriptor 
points to a word that receives the new message count. 
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MAIL$_USER_PERSONAL_NAME 

When you specify MAIL$ USER PERSONAL NAME, MAIL$USER_BEGIN 
returns the personal name string. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 127 characters 
long. 


Specify a value from 0 to 127 in the buffer length field of the item descriptor. 


MAIL$_USER_QUEUE 

When you specify MAIL$ USER_QUEUE, MAIL$USER_BEGIN returns the 
default print queue name. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ USER_RETURN_USERNAME 

When you specify MAIL$¢ USER_RETURN_ USERNAME, MAIL$USER_BEGIN 
returns the user name string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_SIGFILE 

When you specify MAIL$ USER_SIGFILE, MAIL$USER_BEGIN returns 

the default signature file specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string O to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_SUB_DIRECTORY 

When you specify MAIL$¢ USER_SUB DIRECTORY, MAIL$USER_BEGIN 
returns the subdirectory specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string O to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$USER_BEGIN creates and initializes a user database context for 
subsequent calls to other user routines. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Mail Utility (MAIL) Routines MAIL—97 


Mail Utility Routines 
MAIL$USER_DELETE_INFO 


MAIL$USER_DELETE_INFO—Delete Database Record 


Format 


Returns 


Arguments 


Removes a record from the user profile database. 


MAIL$USER_DELETE_INFO context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


User context information to be passed to send routines. The context argument 
is the address of a longword that contains user context information returned by 
MAIL$USER_BEGIN. 


in_item_list 

OpenVMS usage: itmist_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item list is 
terminated by longword value of 0. 


Input Item Codes 


MAIL$_USER_USERNAME 

MAIL$ USER_USERNAME specifies the record to be deleted from the user 
profile database. The buffer address field of the item descriptor points to a 
buffer that contains the user name string encoded in a character string 0 to 31 
characters long. 


Specify a value from 0 to 31 in the buffer length field of the item descriptor. 
The item code MAIL$ USER_USERNAME is required. 
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Output Item 


Description 
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out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


None. 


To delete a record from the user profile database, you must have SYSPRV 
privilege. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOSUCHUSR The specified user name is not valid. 
MAIL$ NOSYSPRV The operation requires the SYSPRV privilege. 
SS$ ACCVIO Access violation. 
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MAIL$USER_END—End Access to the User Profile Database 


Terminates access to the user profile database. 


Format 
MAIL$USER_END context ,in_item_list ,out_item_list 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
User context information to be passed to user routines. The context argument is 
the address of a longword that contains user context information. 
If the Mail utility terminates access to the user profile database successfully, the 
value of the argument context is changed to 0. 
in_item_list 
OpenVMS usage: itmlst_3 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
Item list specifying options for the routine. This routine does not use the in_ 
item_list argument. 
out_item_list 
OpenVMS usage: itmlst_3 
type: longword 
access: write only 
mechanism: by reference 
Item list specifying the information you want the routine to return. This routine 
does not use the out_item_list argument. 
Description 


The MAIL$USER_END routine deallocates the user database context created by 
MAIL$USER_BEGIN as well as all dynamic memory allocated by previous user 
routines. 
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Condition Values Returned 


SS$ NORMAL Normal successful completion. 
MAIL$ INVITMCOD The specified item code is invalid. 
MAIL$ INVITMLEN The specified item length is invalid. 
MAIL$ MISREQITEM The required item is missing. 

SS$ ACCVIO Access violation. 


Any condition value returned by LIB$FREE_VM. 
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MAIL$USER_GET_INFO—Get User Profile Information 


Format 


Returns 


Arguments 


Obtains information about a user from the user profile database. 


MAIL$USER_GET_INFO_ context ,in_item_list ,out_item_list 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


User context information to be passed to user routines. The context argument 
is the address of a longword that contains user context information returned by 
MAIL$USER_BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item list is 
terminated by longword value of 0. 


Input Item Codes 


MAIL$_USER_FIRST 

The Boolean item code MAIL$ USER_FIRST specifies that MAIL$USER_GET_ 
INFO return information in the user profile about the first entry in the user 
profile database. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify MAIL$ USER_FIRST, MAIL$ USER_NEXT or MAIL$ USER_ 
USERNAME in the same call to MAIL$USER_GET_INFO. 
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MAIL$ USER_NEXT 
The Boolean item code MAIL$ USER_NEXT specifies that MAIL$USER_GET_ 
INFO return information in the user profile about the next user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


Do not specify MAIL$ USER_FIRST, MAIL$ USER_NEXT or MAIL$ USER_ 
USERNAME in the same call to MAIL$USER_GET_INFO. 


MAIL$_USER_USERNAME 
The item code MAIL$ USER_USERNAME points to the username string. 


Specify the address of the username string in the buffer address field and 
specify the length of the username string in the buffer length field of the item 
descriptor. 


Do not specify MAIL$ USER_FIRST, MAIL$ USER_NEXT and MAIL$ USER_ 
USERNAME in the same call to MAIL$USER_GET_INFO. 


out_item_list 
OpenVMS usage: itmlst_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


MAIL$ USER_AUTO_PURGE 

When you specify the Boolean item code MAIL$ USER_AUTO PURGE, 
MAIL$USER_GET_INFO returns the value of the automatic purge mail flag 
as a longword value. 


MAIL$ USER_CC_PROMPT 

When you specify the Boolean item code MAIL$ USER_CC_PROMPT, 
MAIL$USER_GET_INFO returns the value of the cc prompt flag as a longword 
value. 


MAIL$_USER_COPY_FORWARD 

When you specify the Boolean item code MAIL$ USER_COPY_FORWARD, 
MAIL$USER_GET_INFO returns the value of the copy self forward mail flag as a 
longword value. 


MAIL$ USER_COPY_REPLY 

When you specify the Boolean item code MAIL$ USER_COPY_REPLY, 
MAIL$USER_GET_INFO returns the value of the copy self reply mail flag 
as a longword value. 


MAIL$ USER_COPY_SEND 

When you specify the Boolean item code MAIL$ USER_COPY_SEND, 
MAIL$USER_GET_INFO returns the value of the copy self send mail flag as 
a longword value. 
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MAIL$_USER_EDITOR 

When you specify MAIL$ USER_EDITOR, MAIL$USER_GET_INFO returns the 
name of the default editor. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ USER_FORWARDING 

When you specify MAIL$ USER FORWARDING, MAIL$USER_GET_INFO 
returns the forwarding address. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ USER_FORM 

When you specify MAIL$ USER_FORM, MAIL$USER_GET_INFO returns the 
default print form string. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_FULL_DIRECTORY 

When you specify MAIL$ USER_FULL_DIRECTORY, MAIL$USER_GET_INFO 
returns the complete directory path of the MAIL subdirectory string. The buffer 
address field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$ USER_NEW_MESSAGES 

When you specify MAIL$ USER_NEW_MESSAGES, MAIL$USER_GET_INFO 
returns the new messages count. The buffer address field of the item descriptor 
points to a word that receives the new message count as a word value. 


MAIL$_USER_PERSONAL_NAME 

When you specify MAIL$ USER_PERSONAL_NAME, MAIL$USER_GET_ 
INFO returns the personal name string. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 127 characters 
long. 


Specify a value from 0 to 127 in the buffer length field of the item descriptor. 


MAIL$_USER_QUEUE 

When you specify MAIL$ USER_QUEUE, MAIL$USER_GET_INFO returns the 
default print queue name string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_RETURN_USERNAME 

When you specify MAIL$ USER_RETURN_ USERNAME, MAIL$USER_GET_ 
INFO returns the user name. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$_USER_SIGFILE 

When you specify MAIL$ USER_SIGFILE, MAIL$USER_GET_INFO returns 
the default signature file specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string O to 255 characters 
long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL$_USER_SUB_DIRECTORY 

When you specify MAIL$ USER_SUB_DIRECTORY, MAIL$USER_GET_INFO 
returns the MAIL subdirectory specification string. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Description 


The MAIL$USER_GET_INFO routine returns information about specified entries 
in the user profile database. If you do not specify a user name, MAIL$USER_ 
GET_INFO returns information about the user name associated with the calling 
process. To obtain information about a user name other than that associated with 
the calling process, you need the SYSNAM privilege. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

MAIL$ CONITMCOD The specified item codes perform conflicting 
operations. 

MAIL$ INVITMCOD The specified item code is invalid. 

MAIL$ INVITMLEN The specified item length is invalid. 

MAIL$ MISREQITEM The required item is missing. 

MAIL$ NOSUCHUSR The specified user name is invalid. 

MAIL$ NOSYSPRV The specified operation requires the SYSPRV 
privilege. 

SS$ ACCVIO Access violation. 
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MAIL$USER_SET_INFO—Add User Profile Information 


Adds or modifies a specified user record in the user profile database. 


Format 
MAIL$USER_SET_INFO context ,in_item_list ,out_item_list 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 
Arguments 
context 
OpenVMS usage: context 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


User context information to be passed to user routines. The context argument 
is the address of a longword that contains user context information returned by 
MAIL$USER_BEGIN. 


in_item_list 

OpenVMS usage: itmlst_3 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 


The item list must include at least one device item descriptor. The item list is 
terminated by longword value of 0. 


Input Item Codes 


MAIL$_USER_CREATE_IF 

The Boolean item code MAIL$ USER_CREATE_IF specifies that MAIL$USER_ 
SET_INFO should create the record for the specified user if it does not already 
exist. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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MAIL$ USER_SET_AUTO_ PURGE 

MAIL$ USER_SET_NO_ AUTO PURGE 

The Boolean item codes MAIL$ USER_SET_AUTO_PURGE and MAIL$ USER_ 
SET_NO AUTO PURGE set and clear the auto purge flag for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ USER_SET_CC_ PROMPT 

MAIL$ USER_SET_NO_CC_ PROMPT 

The Boolean item codes MAIL$ USER_SET_CC_ PROMPT and MAIL$ USER_ 
SET_NO CC PROMPT set and clear the cc prompt flag for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$_USER_SET_COPY_FORWARD 
MAIL$_USER_SET_NO_COPY_FORWARD 

The Boolean item codes MAIL$ USER_SET_COPY_FORWARD and MAIL$_ 
USER_SET_NO_COPY_FORWARD set and clear the copy self forward flag for 
the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$_USER_SET_COPY_REPLY 

MAIL$_USER_SET_NO_COPY_REPLY 

The Boolean item codes MAIL$ USER_SET_COPY_REPLY and MAIL$ USER_ 
SET_NO COPY _REPLY set and clear the copy self reply flag for the specified 
user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ USER_SET_COPY_SEND 

MAIL$_USER_SET_NO_COPY_SEND 

The Boolean item codes MAIL$ USER_SET_COPY_SEND and MAIL$ USER_ 
SET_NO COPY_SEND set and clear the copy self send flag for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$_USER_SET_EDITOR 

MAIL$_USER_SET NO EDITOR 

MAIL$ USER_SET_EDITOR specifies the name of a default editor to be used by 
the specified user. The buffer address field of the item descriptor points toa 
buffer that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET_NO_EDITOR clears the default editor 
field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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MAIL$_USER_SET_FORM 

MAIL$_USER_SET_NO FORM 

MAIL$ USER_SET_ FORM specifies the default print form string for the specified 
user. The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET NO FORM clears the default print 
form field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$_USER_SET_FORWARDING 

MAIL$_USER_SET_NO FORWARDING 

MAIL$ USER_SET_FORWARDING specifies a forwarding address string for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET_NO FORWARDING clears the 
forwarding address field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ USER_SET_NEW_MESSAGES 

MAIL$ USER_SET_NEW_MESSAGES specifies the new message count for the 
specified user. The buffer address field of the item descriptor points to a word 
that contains the new number of new messages. 


MAIL$ USER_SET_PERSONAL_NAME 

MAIL$ USER_SET_NO_PERSONAL_NAME 

MAIL$ USER_SET_PERSONAL_NAME specifies a personal name string for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 127 characters long. 


Specify a value from 0 to 127 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET_NO PERSONAL_NAME clears the 
personal field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$_USER_SET_QUEUE 

MAIL$_USER_SET_NO_QUEUE 

MAIL$ USER_SET_QUEUE specifies a default print queue name string for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET_NO QUEUE dlears the default print 
queue field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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MAIL$ USER_SET_SIGFILE 

MAIL$ USER_SET_NO_SIGFILE 

MAIL$ USER_SET_SIGFILE specifies a signature file specification for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET_NO_SIGFILE clears the signature file 
field for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ USER_SET_SUB_ DIRECTORY 

MAIL$ USER_SET_ NO SUB_DIRECTORY 

MAIL$ USER_SET_SUB_DIRECTORY specifies a MAIL subdirectory. The 
buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 


Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


The Boolean item code MAIL$ USER_SET_NO_SUB_DIRECTORY disables the 
use of a MAIL subdirectory for the specified user. 


Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 


MAIL$ USER_USERNAME 

MAIL$ USER_USERNAME specifies the record to be modified in the user 
profile database and points to the user name string. The buffer address field 
of the item descriptor points to a buffer that contains a character string 0 to 31 
characters long. 


Specify a value from 0 to 31 in the buffer length field of the item descriptor. 


out_item_list 
OpenVMS usage: itmist_3 


type: longword 
access: write only 
mechanism: by reference 


Item list specifying the information you want the routine to return. The out_ 
item_list argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 


Codes 


None. 
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Description 


The MAIL$USER_SET_INFO routine modifies specified records in the user 
profile database. If you do not specify a user name, the routine modifies the user 
record associated with the calling process. 


To modify any user record other than that associated with the calling process, 
you must have SYSPRV privilege. However, if you want to add or modify only the 
forwarding address of another user, SYSNAM privilege is sufficient. 


Condition Values Returned 


SS$ NORMAL 
MAIL$ CONITMCOD 


MAIL$ ILLCHAR 


MAIL$ ILLPERNAM 


MAIL$ ILLSUBDIR 


MAIL$_INVITMCOD 
MAIL$_INVITMLEN 
MAIL$ MISREQITEM 
MAIL$ NAMTOOBIG 
MAIL$ NOTSUBDIR 


MAIL$ NOSUCHUSR 


MAIL$ NOSYSNAM 
MAIL$ NOSYSPRV 
SS$ ACCVIO 
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Normal successful completion. 


The specified item codes perform conflicting 
operations. 


Unacceptable character in personal name. Utility 
returns three formatted ASCII output (FAO) 
arguments including the illegal character, the 
length of the string, and the string address. 


Personal name formatted improperly. Returns 
an FAO argument containing the improperly 
formatted personal name. 


Illegal subdirectory specification. Returns an 
FAO argument containing the subdirectory 
string. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

Specified name exceeds 255-character limit. 


No such subdirectory. Returns an FAO argument 
containing the subdirectory string. 


Nosuch user. Returns the name of the unfound 
user. 


Caller needs SYSNAM privileges. 
Caller needs system privileges. 
Access violation. 


17 


National Character Set (NCS) Utility Routines 


This chapter describes the National character set (NCS) utility routines. The 
NCS utility provides a common facility for defining and accessing collating 
sequences and conversion functions. Collating sequences are used to compare 
strings for sorting purposes. Conversion functions are used to derive an altered 
form of an input string based on an appropriate conversion algorithm. 


17.1 Introduction to NCS Routines 


Using NCS, you can formulate collating sequences and conversion functions and 
register them in an NCS library. The NCS routines provide a programming 
interface to NCS that lets you access the collating sequences and conversion 
functions from an NCS library for doing string comparisons. 


Typically, NCS collating sequences are selective subsets of the multinational 
character set. They are used extensively in programming applications involving 
various national character sets. For example, a program might use the Spanish 
collating sequence to assign appropriate collating weight to characters from the 
Spanish national character set. Another program might use the French collating 
sequence to assign appropriate collating weight to characters in the French 
national character set. 


In addition to providing program access to collating sequences and conversion 
functions in an NCS library, the NCS routines provide a means for saving 
definitions in a local file for subsequent use by the comparison and conversion 
routines. 


17.1.1. List of NCS Routines 
Table 17-1 lists the individual NCS routines. 


Table 17-1 NCS Routines 


Routine Description 

NCS$COM PARE Compares two strings using a specified collating sequence as 
comparison basis. 

NCS$CONVERT Converts a string using the specified conversion function. 

NCS$END_CF Terminates the use of a conversion function by the calling 
program. 

NCS$END_CS Terminates the use of a collating sequence by the calling 
program. 

NCS$GET_CF Retrieves the definition of the named conversion function 


from the NCS library. 
(continued on next page) 
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Table 17-1 (Cont.) NCS Routines 


Routine Description 

NCS$GET_CS Retrieves the definition of the named collating sequence from 
the NCS library. 

NCS$RESTORE_CF Permits the calling program to restore the definition of a 
“saved” conversion function from a database or an OpenVMS 
RMS file. 

NCS$RESTORE_CS Permits the calling program to restore the definition of a 


“saved” collating sequence from a database or an RMS file. 


NCS$SAVE_CF Provides the calling program with information that permits 
the application to store the definition of a conversion function 
in a local database or an RMS file. 


NCS$SAVE_CS Provides the calling program with information that permits 
the application to store the definition of a collating sequence 
in a local database or an RMS file. 


17.1.2 Sample Application Process 
In a typical application, the program does the following: 


1. Prepares a string for comparison. 


2. Makes a call tothe NCS$GET routine, specifying the appropriate collating 
sequence. 


3. Makes one or more calls to the NCS$COMPARE routine, which does the 
actual comparison. 


4. Terminates the comparison with a call to the NCS$END routine. 
The program can also include the use of conversion functions in preparation for 
the comparison routines. 

17.2 Using the NCS Utility Routines: Examples 


This section includes two examples of how to use NCS utility routines in program 
applications: 


Example 17-1 illustrates the use of NCS utility routines in a HP Fortran for 
OpenVMS program. 


Example 17-2 illustrates the use of NCS routines in a HP C for OpenVMS VAX 
program. 


Note 


Each programming language provides an appropriate mechanism for 
defining symbols, status codes, completion codes, and other relevant 
information. 


NCS-2. National Character Set (NCS) Utility Routines 


National Character Set (NCS) Utility Routines 
17.2 Using the NCS Utility Routines: Examples 


Example 17-1 Using NCS Routines in a HP Fortran for OpenVMS Program 


ak a? i 


999 


ROGRAM NCS EXAMPLE 


HARACTER*80 CSSTRING, STRING1, STRING2 
NTEGER* 4 CSLENGTH, LENGTH1 , LENGTH2, CSID, STATUS , RESULT 
NTEGER*4 NCSSGET_CS,NCSSCOMPARE, NCSSEND_CS 


P 
C 
I 
I 
CHARACTER*1 CMP (3) 
C 
C 
C 


P(1) = ' 
P(2) = ' 
Pi(3) 


! 
! 
i 


va 


Read the name of the collating sequence.. 


WRITE (6,30) 
READ (5,15,END=999) CSLENGTH, CSSTRING 
FORMAT(’ Collating Sequence: ') 


Get the collating sequence from the NCS library 


CSID = 0 
STATUS = NCSSGET_CS (CSID, CSSTRING(1:CSLENGTH) ) 
IF ((STATUS .AND. 1) .NE. 1) THEN 

CALL LIBSSIGNAL (%VAL(STATUS) ) 

ENDIF 


Read two strings to be compared according to the collating sequence 


WRITE (6,10) 
READ (5,15,END=999) LENGTH1,STRING1 
WRITE (6,20) 
READ (5,15,END=999) LENGTH2,STRING2 


IF (LENGTH1 .EQ. 0 .AND. LENGTH2 .EQ. 0) THEN 
GOTO 200 
ENDIF 


FORMAT(’ Stringl: ') 
FORMAT(’ String2: ') 
FORMAT (q,a80) 


Compare the strings 
result = ncs$compare (csid, stringl(1l:length1), string2(1:length2) ) 
Display the results of the comparison 


WRITE (6,40) STRING1(1:LENGTH1), CMP(RESULT+2), STRING2(1:LENGTH2) 
FORMAT(’ ',A,' ',A,' ',A) 
GOTO 100 


Come here if both inputs are blank -- we are done. 
Call NCSSEND_CS to free any storage used to hold the CS. 


STATUS = NCSSEND CS (CSID) 

IF ((STATUS .AND. 1) .NE. 1) THEN 
CALL LIBSSIGNAL (%VAL(STATUS) ) 
ENDIF 

CALL EXIT 


CONTINUE 
END 
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Example 17-2 Using NCS Routines in a HP C for OpenVMS VAX Program 


/* 
kK penne n nnn nnn 222222 nnn 222222222222 22222222222222=2=2=2==2=2==2=2============ 
kk 
** NCS EXAMPLE.C 
aK ~ 
** NCS conversion function example using the VAX C programming language 
kk 
kA pono nnn n nee 2n 2222222222222 22222222222222222222=2=2=2=22=222=2============ 
*/ 
/* 
Me aoe eee eee eee ee ee ee ee ee eee eleiere eeleie ate eye ty rs tp a is i ay i es ne 
** Header files 
yf 
# include "sys$library:descrip.h" /* Descriptor macros */ 
# include "sys$library:rms.h" /* RMS structure definitions */ 
# include "sysS$library:rmsdef.h" /* RMS completion codes */ 
# include "sys$share:ssdef.h" /* System service completion */ 
/* codes */ 
# include "sys$library:stdio.h" /* Standard I/O definitions */ 
/* 
VOR mere So SS Se SSS erie slate a SiStieia alate e Sew oe See ok ee eee eee eee eee sees 
** Data definitions 
*/ 
#define SIZE 1024 /* Maximum record size */ 
unsigned long int 
cfid, /* Address of conversion */ 
/* function */ 
expected status, /* Expected return status */ 
rms_status, /* RMS return status */ 
status; /* Function return status */ 
unsigned short int 
return length; /* Length of returned string in */ 
/* bytes */ 
char 
file [NAM$C_MAXRSS], /* File name */ 
inrec [SIZE], /* Input record */ 
outrec [SIZE] ; /* Output record */ 
SDESCRIPTOR (cfname_d, "EDT _VT2xx") ; /* Conversion function name */ 
/* descriptor x / 
SDESCRIPTOR(prompt_d," File: "); /* Prompt string descriptor */ 
SDESCRIPTOR (file _d, file); /* File name descriptor */ 
SDESCRIPTOR(inrec_d,inrec) ; /* Input record descriptor */ 
SDESCRIPTOR (outrec_d,outrec) ; /* Output record descriptor */ 
struct FAB infab; /* Input file access block */ 
struct RAB inrab; /* Input record access block */ 
/* 
MRS reese Gie SSeS Se aS a ey SS is Se Se Sissies eta Sia te ete eee eee eee eee ee Se 
** Function prototypes 
*/ 
void status_check() ; 
/* - 
kK pono en nnn e222 2222222222222 222222222222222522222=2=2=2==2=222=2============ 
*/ 
main () 
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Example 17-2 (Cont.) Using NCS Routines in a HP C for OpenVMS VAX 


Program 

/* 
We Secs leeecsemesseesSeeeeseeeee eee ee oe Oe ee Sees oe eee See eee 
** Initialize RMS user structures for the file. 
*/ 
infab = cc$rms_fab; /* Initialize to default FAB */ 

/* values */ 
infab.fab$1_fna = file; /* Now supply our specific */ 

/* values */ 
infab.fabSb fns = NAMSC_MAXRSS; 
inrab = cc$rms_rab; /* Initialize to default RAB */ 

/* values */ 
inrab.rab$l_ fab = &infab; /* Now supply our specific */ 

/* values */ 
inrab.rab$l_ubf = inrec; 
inrab.rab$w_usz = SIZE; 
/* 
IOS i Sg a Sy tt NN Sh eh hi hh he Se el Se 


** Get the EDT VT2xx conversion function from the default NCS library 
af 

cfid = 0; /* Initialize ID */ 

status = nesSget_cf(&cfid, &cfname_d,0) ; 

status_check(status,SS$ NORMAL) ; 

je - 

Seo seaeiat aaa aeee ease aS SeSSaS cece aececaceeeoee eS cSSacSscamacsscesaciastaaa:o aie. 
** Get the file to be converted and set the length of the returned file 
** name 

ay 

status = libSget_input (&file d, &prompt_d, &return_length) ; 
status_check(status,SS$ NORMAL) ; 

file d.dsc$w_ length = return length; 


Se asceasassceciesseceissiscisciaciasceceecaecee cease ee See cece cece cece ec cece See. 
** Open the input file to be converted and connect to the RAB 

si 

rms_status = sysSopen(&infab,0,0) ; 

status_check(rms_status,RMSS$ NORMAL) ; 


rms_ status = sysSconnect (&inrab,0,0) ; 
status_check(rms_status,RMS$ NORMAL) ; 


BOS | a ey ey sy a aia a tN ta ee ee eh eal ee eh eh eh te eh eh ee ren ees 


** Read each record from the file, convert the input string to EDT 
** fallback, and write the result to the output 


ue 

while (TRUE) 

{ 
/* 
OX (ciclo eo eee ee eee mec emcee ee eee eee See eee eee eee eee ee ee ee eee eee See 
** Read each record 
‘7 
rms_status = sys$get(&inrab,0,0) ; 
if (rms_status == RMS$ EOF) /* Reached end of file */ 

break; 
else 

status_check(rms_status,RMS$ NORMAL); /* Read a record */ 


(continued on next page) 
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Example 17-2 (Cont.) Using NCS Routines in a HP C for OpenVMS VAX 
Program 
/* 
RX cisiciatociocceicciacocece cece eee eee eee eee eee ee eee ee eee eee ee ee ae Sie oe 


** Call NCSSCONVERT to convert the input string to EDT fallback 
kk 

** e.g. Convert form feed to <FF>, escape to <ESC>, et cetera 
7] 

inrec_d.dsc$w_length = inrab.rab$w_rsz; 

status = ncs$convert (&cfid, &inrec_d,&outrec_d, &return_length) ; 
status _check(status,SS$ NORMAL) ; 

outrec_d.dsc$w_ length = return_length; 


EX sossseaeasciee seas eee Ss Sel Si eS Sa eS el ee ee 
** Write the result to the output, SYSSOUTPUT in this case 

*/ 

status = libSput output (&outrec d); 

status_check(status,SS$ NORMAL) ; 

outrec_d.dsc$w_length = SIZE; 


** Close the input file. 

ty 

rms_status = sys$close(&infab,0,0) ; 
status_check(rms_status,RMS$ NORMAL) ; 
/* 


** Free any storage used to hold the conversion function. 
¥/ 

status = ncs$end_cf(&cfid) ; 

status _check(status,SS$ NORMAL) ; 


void status_check (status, expected_status) 


/* 


RKO eee ee ee ee ee ee ee ee ee ee eee ee eee eee eee eee ee eee eee == === 


kk 


** Checks the function return status against the one expected, and exits upon 
** error. Otherwise, return to the main program. 


if (status != expected status) 
sysSexit (status) ; 

else 
return; 


17.3 NCS Routines 
This section describes the NCS routines. 


Note that several routines contain the heading Condition Value Signaled to 
indicate that the condition value originates in another utility. 
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NCS$COMPARE—Compare Strings 


Format 


Returns 


Arguments 


The NCS$COMPARE routine compares two strings using a specified collating 
sequence as a comparison basis. 


NCS$COMPARE cs _id ,string_1 ,string_2 


OpenVMS usage: integer 


type: longword integer (signed) 
access: write only 
mechanism: by value 


Longword condition value. Most routines return a condition value in RO, but 
the NCS$COMPARE routine uses RO to return the result of the comparison, as 
shown in the following table: 


Returned Value Comparison Result 

-1 string_lis less than string 2 

0 string _1is equal to string 2 

1 string _1 is greater than string 2 


The NCS$COMPARE routine uses the Signaling Mechanism to indicate 
completion status as described under Condition Value Signaled. 


cs_id 

OpenVMS usage: identifier 

type: longword integer (unsigned) 
access: read only 

mechanism: by reference 


Address of a longword that NCS uses to identify a collating sequence. The cs id 
argument is required and can be obtained by a call to the NCS$GET_CS routine. 


All calls to the NCS$COMPARE routine and the call to the NCS$END_CS 
routine that terminates the comparison must pass this longword identifier. Upon 
completion, the NCS$END_CS routine releases the memory used to store the 
collating sequence and sets the value of the longword identifier to 0. 


string_1 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Descriptor (length and address) of the first string. 
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NCS$COMPARE 
string 2 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Descriptor of the second string. 


Description 


The NCS$COMPARE routine compares two strings using the specified collating 
sequence as the comparison basis. The routine indicates whether the value of the 
first string is greater than, less than, or equal to the value of the second string. 


Condition Value Signaled 


STR$ ILLSTRCLA Illegal string class. Severe error. The descriptor 
of string_1 or string_2, or both, contains a class 
code not supported by the OpenVMS Calling 
Standard. 
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NCS$CONVERT—Convert String 


Format 


Returns 


Arguments 


The NCS$CONVERT routine converts a string using the specified conversion 
function. 


NCS$CONVERT  cf_id ,source ,dest [,ret_length] [,not_cvt] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


cf_id 

OpenVMS usage: identifier 

type: longword integer (unsigned) 
access: read only 

mechanism: by reference 


Address of a longword that NCS uses to identify a conversion function. The cf_id 
argument is required and can be obtained by a call tothe NCS$GET _CF routine 


All calls to the NCS$CONVERT routine and the call to the NCS$END_CF 
routine that terminates the conversion must pass this longword identifier. Upon 
completion, the NCS$END_CF routine releases the memory used to store the 
conversion function and sets the value of the longword identifier to 0. 


source 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Descriptor of source string. 


dest 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Descriptor of destination string. 
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NCS$CONVERT 
ret_length 
OpenVMS usage: word unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Length of converted string. 


not_cvt 

OpenVMS usage: word unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Number of characters in the source string that were not fully converted. 


Description 


Using the specified conversion function, the NCS$CONVERT routine converts the 
source string and stores the result in the specified destination. Optionally, the 
calling program can request that the routine return the length of the converted 
string as well as the number of characters that were not fully converted. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

NCS$ NOT_CF Name of identifier does not refer to a conversion 
function. 

STR$ TRU Successful completion. However, the resultant 


string was truncated because the storage 
allocation for the destination string was 
inadequate. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 


Any value signaled by STR$COPY_DX or STR$ANALYZE _SDESC. 


NCS-10 National Character Set (NCS) Utility Routines 


National Character Set (NCS) Utility Routines 
NCS$END_CF 


NCS$END_CF—End Conversion Function 


Format 


Returns 


Argument 


Description 


The NCS$END_CF routine terminates a conversion function. 


NCS$END_CF  cf_id 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


cf_id 

OpenVMS usage: _ identifier 

type: longword integer (unsigned) 
access: modify 

mechanism: by reference 


Address of a longword that NCS uses to store a nonzero value identifying a 
conversion function. 


The cf_id argument is required. 


The NCS$END_CF routine indicates to NCS that the calling program no longer 
needs the conversion function. NCS releases the memory space allocated for the 
coversion function and sets the value of the longword identifier to 0. 


Condition Values Returned 


NCS$ NORMAL Normal successful completion. The longword 
identifier value is set to 0. 

NCS$ NOT_CF Name of identifier does not refer to a conversion 
function. 
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NCS$END_CS—End Collating Sequence 


Format 


Returns 


Argument 


Description 


The NCS$END_CS routine terminates a collating sequence. 


NCS$END_CS._ cs_id 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


cs_id 

OpenVMS usage: identifier 

type: longword integer (unsigned) 
access: modify 

mechanism: by reference 


Address of a longword that NCS uses to store a nonzero value identifying a 
collating sequence. 


The cs id argument is required. 


The NCS$END _CS routine indicates to NCS that the calling program no longer 
needs the collating sequence. NCS releases the memory space allocated for the 
collating sequence and sets the value of the longword identifier to 0. 


Condition Values Returned 


NCS$ NORMAL Normal successful completion. The longword 
identifier value is set to 0. 

NCS$ NOT_CS Name of identifier does not refer to a collating 
sequence. 
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NCS$GET_CF—Get Conversion Function 


Format 


Returns 


Arguments 


The NCS$GET_CF routine retrieves the definition of the named conversion 
function from the NCS library. 


NCS$GET_CF  cf_id [,cfname] [,librar] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


cf_id 

OpenVMS usage: identifier 

type: longword integer (unsigned) 
access: modify 

mechanism: by reference 


Address of a longword used by NCS to identify a conversion function. The 
calling program must ensure that the longword contains 0 before invoking 

the NCS$GET_CF routine because the routine stores a nonzero value in the 
longword. The nonzero value identifies the conversion function. All subsequent 
calls to the NCS$CONVERT routine and the call to the NCS$END_CF routine to 
terminate the conversion function pass the longword identifier. When it completes 
the conversion, the NCS$END_CF routine releases the memory used to store the 
conversion function and sets the value of the longword identifier to 0. 


The conversion function identifier enhances modular programming and permits 
concurrent use of multiple conversion functions within a program. 


The calling program should not attempt to interpret the contents of the longword 
identifier. 


The cf_id argument is required. 


cfname 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Name of the conversion function being retrieved. 
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NCS$GET_CF 
librar 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Name of the library where the conversion function is stored. 


Description 
The NCS$GET_CF routine extracts the named conversion function from the 
specified NCS library. 


If the calling program omits the cfname argument, an “identity” conversion 
function padded with NUL characters (hex 0) is provided. The identity conversion 
function effectively leaves each character unchanged by converting each character 
to itself. For example, A becomes A, B becomes B, C becomes C, and so forth. 


If the calling program omits the librar argument, NCS accesses the default NCS 
library. 


Condition Values Returned 


NCS$ DIAG Operation completed with signaled diagnostics. 

NCS$ NOT_CF Name of identifier does not refer to a conversion 
function. 

NCS$ NOT FOUND Name of identifier not found in the NCS library. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$GET_CS—Get Collating Sequence 


Format 


Returns 


Arguments 


The NCS$GET_CS routine retrieves the definition of the named collating 
sequence from the NCS library. 


NCS$GET_CS cs _id [,csname] [,librar] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


cs_id 

OpenVMS usage: _ identifier 

type: longword integer (unsigned) 
access: modify 

mechanism: by reference 


Address of a longword that NCS uses to store a nonzero value identifying a 
collating sequence. The calling program must ensure that the longword identifier 
contains 0 before invoking the NCS$GET_CS routine. 


All subsequent calls to the NCS$COMPARE routine and the call to the 
NCS$END_CS routine that terminates the use of the collating sequence 

must pass this longword identifier. Upon completion of the comparisons, the 
NCS$END_CS routine releases the memory used to store the collating sequence 
and sets the value of the longword identifier to 0. 


The collating sequence identifier enhances modular programming and permits 
concurrent use of multiple collating sequences within a program. 


The calling program should not attempt to interpret the contents of the longword 
identifier. 


The cs_id argument is required. 


csname 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Name of the collating sequence being retrieved. 


National Character Set (NCS) Utility Routines NCS-15 


National Character Set (NCS) Utility Routines 


NCS$GET_CS 
librar 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


File specification of the library where the collating sequence is stored. 


Description 


The NCS$GET_CS routine extracts the named collating sequence from the 
specified NCS library. If the calling program omits the csname argument, NCS 
creates a collating sequence that uses the “native” collating sequence as a basis 
for the comparisons. This collating sequence is padded with NUL characters (hex 
0). 


If the calling program omits the librar argument, NCS accesses the default NCS 
library. 


Condition Values Returned 


NCS$ DIAG Operation completed with signaled diagnostics. 

NCS$ NOT_CS Name of identifier does not refer to a collating 
sequence. 

NCS$ NOT FOUND Name of identifier not found in the NCS library. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 


NCS-16 National Character Set (NCS) Utility Routines 


National Character Set (NCS) Utility Routines 
NCS$RESTORE_CF 


NCS$RESTORE_CF—Restore Conversion Function 


Format 


Returns 


Arguments 


The NCS$RESTORE _CF routine permits the calling program to restore the 
definition of a saved conversion function from a database or a file. 


NCS$RESTORE_CF  cf_id [,length] [,address] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


cf_id 

OpenVMS usage: identifier 

type: longword integer (unsigned) 
access: write only 

mechanism: by reference 


Address of a longword that NCS uses to identify a conversion function. 
The cf_id argument is required. 


length 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword that the calling program uses to indicate the length of the conversion 
function being restored. 


address 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword that the calling program uses as a pointer to the conversion function 
being restored. 
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Description 


The NCS$RESTORE _CF routine, used in conjunction with the NCS$SAVE_CF 
routine, permits the application program to keep a local copy of the conversion 
function. The NCS$SAVE_CF routine obtains the length and location of the 
conversion function and returns it to the application program. The application 
program subsequently provides this information to the NCS$RESTORE_CF 
routine, which uses it to access the conversion function. 


This routine also does some integrity checking on the conversion function as it is 
being processed. 


Condition Value Returned 


NCS$ NOT_CF Name of identifier does not refer to a conversion 
function. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$RESTORE_CS—Restore Collating Sequence 


Format 


Returns 


Arguments 


The NCS$RESTORE _CS routine permits the calling program to restore the 
definition of a “saved” collating sequence from a database or a file. 


NCS$RESTORE_CS._ cs _id [,length] [,address] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


cs_id 

OpenVMS usage: identifier 

type: longword integer (unsigned) 
access: write only 

mechanism: by reference 


Address of a longword that NCS uses to identify a collating sequence. 
The cs_id argument is required. 


length 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword that the calling program uses to indicate the length of the collating 
sequence being restored. 


address 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword that the calling program uses as a pointer to the collating sequence 
being restored. 
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Description 


The NCS$RESTORE CS routine, used in conjunction with the NCS$SAVE_CS 
routine, permits the application program to keep a local copy of the collating 
sequence. The NCS$SAVE_CS routine obtains the length and location of the 
collating sequence and returns it to the application program. The application 
program subsequently provides this information to the NCS$RESTORE_CS 
routine, which uses it to access the collating sequence. 


This routine also does some integrity checking on the collating sequence as it is 
being processed. 


Condition Value Returned 


NCS$ NOT_CS Name of identifier does not refer to a collating 
sequence. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$SAVE_CF—Save Conversion Function 


The NCS$SAVE_CF routine provides the calling program with information that 
permits the application to store the definition of a conversion function in a local 
database or a file rather than in the NCS library. 


Format 
NCS$SAVE_CF  cf_id [,length] [,address] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 
Arguments 
cf_id 
OpenVMS usage: _ identifier 
type: longword integer (unsigned) 
access: read only 
mechanism: by reference 


Address of a longword that NCS uses to identify a conversion function. 
The cf_id argument is required. 


length 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Longword used to store the length of the specified conversion function. 


address 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Longword used to store the address of the specified conversion function. 
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Description 


The NCS$SAVE_CF routine, used in conjunction with the NCS$RESTORE_CF 
routine, permits the application program to store a conversion function definition 
in a local file or in a database. When the calling program specifies the conversion 
function identifier, NCS returns the location of the definition and its length in 
bytes, permitting the calling program to store the definition locally, rather than 
in an NCS library. Subsequently, the application supplies this information to the 
NCS$RESTORE_CF routine, which restores the conversion function to a form 
that can be used by the NCS$CONVERT routine 


This routine also does some integrity checking on the conversion function as it is 
being processed. 


Condition Value Returned 


NCS$ NOT_CF Name of identifier does not refer to a conversion 
function. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$SAVE_CS—Save Collating Sequence 


The NCS$SAVE_CS routine provides the calling program with information that 
permits the application program to store the definition of a collating sequence in 
a database or a file rather than in the NCS library. 


Format 
NCS$SAVE_CS_ cs_id [,length] [,address] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 
Arguments 
cs_id 
OpenVMS usage: identifier 
type: longword integer (unsigned) 
access: read only 
mechanism: by reference 


Address of a longword that NCS uses to identify a collating sequence. 
The cs_id argument is required. 


length 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Longword that NCS uses to indicate the length of the specified collating sequence 
to the calling program. 


address 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Longword that NCS uses to indicate the address of the specified collating 
sequence to the calling program. 
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Description 


The NCS$SAVE_CS routine, used in conjunction with the NCS$RESTORE_CS 
routine, permits the application program to store a collating sequence definition 
in a local file or in a database. When the calling program specifies the collating 
sequence identifier, NCS returns the location of the definition sequence and its 
length in bytes, permitting the calling program to store the definition locally, 
rather than in a library. Subsequently, the application supplies this information 
to the NCS$RESTORE_CS routine, which restores the collating sequence to a 
form that can be used by the NCS$COMPARE routine. 


This routine also does some integrity checking on the collating sequence as it is 
being processed. 


Condition Value Returned 


NCS$ NOT_CS Name of identifier does not refer to a collating 
sequence. 


Condition Values Signaled 


LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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Print Symbiont Modification (PSM) Routines 


The print symbiont modification (PSM) routines allow you to modify the behavior 
of the print symbiont supplied with the operating system. 
18.1 Introduction to PSM Routines 


The print symbiont processes data for output to standard line printers and 
printing terminals by performing the following functions: 


e« Reading the data from disk 
e Formatting the data 
e Sending the data to the printing device 


*« Composing separation pages (flag, burst, and trailer pages) and inserting 
them into the data stream for printing 


Some of the reasons for modifying the print symbiont include the following: 


e To include additional information on the separation pages (flag, burst, and 
trailer) or to format them differently 


e To filter and modify the data stream sent to the printer 
e To change some of the ways that the symbiont controls the printing device 


You might not always be able to modify the print symbiont to suit your needs. 
For example, you cannot modify the: 


e Symbiont’s control logic or the sequence in which the symbiont calls routines 
e Interface between the symbiont and the job controller 
If you cannot modify the print symbiont to suit your needs, you can write your 


own symbiont. However, HP recommends that you modify the print symbiont 
rather than write your own. 


The rest of this chapter contains the following information about PSM routines: 


e Section 18.2 contains an overview of the print symbiont and of symbionts 
in general. It explains concepts such as “symbiont streams”; describes the 
relationship between a symbiont, a device driver, and the job controller; and 
gives an overview of the print symbiont’s internal logic. 

This section is recommended for those who want to either modify the print 
symbiont or write a new symbiont. 


e Section 18.3 details the procedure for modifying the print symbiont. 
It includes an overview of the entire procedure, followed by a detailed 
description of each step. 


e Section 18.4 contains an example of a simple modification to the print 
symbiont. 
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e Section 18.5 describes each PSM routine and the interface used by the 
routines you substitute for the standard PSM routines. 


18.2 Print Symbiont Overview 


The operating system supplies two symbionts: a print symbiont, which is an 
output symbiont, and a card reader, which is an input symbiont. An output 
symbiont receives tasks from the job controller, whereas an input symbiont sends 
jobs to the job controller. The card reader symbiont cannot be modified. You can 
modify the print symbiont, described in this section, using PSM routines. 


There are two types of output symbiont: device and server. A device symbiont 
processes data for output to a device, for example, a printer. A server symbiont 
also processes data but not necessarily for output to a device, for example, a 
symbiont that copies files across a network. The operating system supplies no 
server symbionts. 


18.2.1 Components of the Print Symbiont 
The print symbiont includes the following major components: 


e« PSM routines that are used to modify the print symbiont 


e Routines that implement input, format, and output services in the print 
symbiont 


e Routines that implement the internal logic of the print symbiont 


The print symbiont is implemented using the Symbiont Services facility. This 
facility provides communication and control between the job controller and 
symbionts through a set of Symbiont/} ob Controller Interface routines (GMB 
routines), which are documented in Chapter 19. 


All of these routines are contained in a shareable image with the file specification 
SYS$SHARE:SMBSRVSHR.EXE. 


18.2.2 Creation of the Print Symbiont Process 


The print symbiont is a device symbiont, receiving tasks from the job controller 
and processing them for output to a printing device. In the operating system, 
the existence of a print symbiont process is linked to the existence of at least one 
print execution queue that is started. 


The job controller creates the print symbiont process by calling the $CREPRC 
system service; it does this whenever either of the following conditions occurs: 


e A print execution queue is started (from the stopped state) and no symbiont 
process is running the image specified with the START/QUEUE command. 


A print execution queue is started by means of the DCL command 
START/QUEUE. Use the /PROCESSOR qualifier with the START/QUEUE 
command to specify the name of the symbiont image that is to service an 
execution queue; if you omit /PROCESSOR, then the default symbiont image 
is PRTSMB. 


¢« Currently existing symbiont processes suited to a print execution queue 
cannot accept additional devices; that is, the symbionts have no more 
available streams. In such a case, the job controller creates another print 
symbiont process. The next section discusses symbiont streams. 


The print symbiont process runs as a detached process. 
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18.2.3 Symbiont Streams 


A stream is a logical link between a print execution queue and a printing device. 
When the queue is started (by means of START/QUEUE), the job controller 
creates a stream linking the queue with a symbiont process. Because each 

print execution queue has a single associated printing device (specified with the 
/ON =device qualifier in the INITIALIZE/QUEUE or START/QUEUE command), 
each stream created by the job controller links a print execution queue, a 
symbiont process, and the queue’s associated printer. 


A symbiont that can support multiple streams simultaneously (that is, multiple 
print execution queues and multiple devices) is termed a multithreaded symbiont. 
The job controller enforces an upper limit of 16 on the number of streams that 
any symbiont can service simultaneously. 


Therefore, in the operating system environment, only one print symbiont process 
is needed as long as the number of print execution queues (and associated 
printers) does not exceed 16. If there are more than 16 print execution queues, 
the job controller creates another print symbiont process. 


The print symbiont is, therefore, a multithreaded symbiont that can service as 
many as 16 queues and devices, and you can modify it to service any number of 
queues and devices as long as the number is less than or equal to 16. 


A symbiont stream is “active” when a queue is started on that stream. The print 
symbiont maintains a count of active streams. It increments this count each 
time a queue is started and decrements it when a queue is stopped with the DCL 
command STOP/QUEUE/NEXT or STOP/QUEUE/RESET. When the count falls 
to zero, the symbiont process exits. The symbiont does not decrement the count 
when the queue is paused by STOP/QUEUE. 


Figure 18-1 shows the relationship of generic print queues, execution print 
queues, the job controller, the print symbiont, printer device drivers, and printers. 
The lines connecting the boxes denote streams. 


Figure 18-1 Multithreaded Symbiont 
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18.2.4 Symbiont and Job Controller Functions 


This section compares the roles of the symbiont and job controller in the execution 
of print requests. You issue print requests using the PRINT command. 
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The job controller uses the information specified on the PRINT command line to 
determine the following: 


¢ Which queue to place the job in ((QUEUE, /REMOTE, /LOWERCASE, and 
/DEVICE) 


e« How many copies to print (/COPIES and /) OB COUNT) 


e Scheduling constraints for the job (/PRIORITY, /AFTER, /HOLD, /FORM, 
/CHARACTERISTICS, and /RESTART) 


¢ How and whether to display the status of jobs and queues (/NOTIFY, 
/OPERATOR, and /IDENTIFY) 


The print symbiont, on the other hand, interprets the information supplied with 
the qualifiers that specify this information: 


e¢ Whether to print file separation pages (/BURST, /FLAG, and /TRAILER) 


¢ Information to include when printing the separation pages (NAME and 
/NOTE) 


e Which pages to print (/PAGES) 
¢« How to format the print job (/AFEED, /SPACE, and /PASSALL) 
¢ How to set up the job (/SETUP) 


The print symbiont, not the job controller, performs all necessary device-related 
functions. It communicates with the printing device driver. For example, when a 
print execution queue is started (by means of START/QUEUE/ON =device) and the 
stream is established between the queue and the symbiont, the symbiont parses 
the device name specified by the /ON qualifier in the START/QUEUE command, 
allocates the device, assigns a channel to it, obtains the device characteristics, 
and determines the device class. In versions of the operating system prior to 
Version 4.0, the job controller performed these functions. 


The print symbiont’s output routine returns an error to the job controller if the 
device class is neither printer nor terminal. 


18.2.5 Print Symbiont Internal Logic 


The job controller deals with units of work called jobs, while the print symbiont 
deals with units of work called tasks. A print job can consist of several print 
tasks. Thus, in the processing of a print job, the job controller’s role is to divide 
a print job into one or more print tasks, which the symbiont can process. The 
symbiont reports the completion of each task to the job controller, but the 
symbiont contains no logic to determine that the print job as a whole is complete. 


In the processing of a print task, the symbiont performs three basic functions: 
input, format, and output. The symbiont performs these functions by calling 
routines to perform each function. 


The following steps describe the action taken by the symbiont in processing a 
task: 


1. The symbiont receives the print request from the job controller and stores it 
in a message buffer. 


2. Thesymbiont searches its list of input routines and selects the first input 
routine that is applicable to the print task. 
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3. Theinput routine returns a data record to the symbiont’s input buffer or in a 
buffer supplied by the input routine. 


4. Data in the input buffer is moved to the symbiont’s output buffer by the 
formatting routines, which format it in the process. 


Data in the output buffer is sent to the printing device by the output routine. 


When an input routine completes execution, that is, when it has no more 
input data to process, the symbiont selects another applicable input routine. 
Steps 3, 4, and 5 are repeated until all applicable input routines have 
executed. 


7. The symbiont informs the job controller that the task is complete. 


Figure 18-2 illustrates the steps taken by the symbiont in the processing of a 
print task. 


Figure 18-2 Symbiont Execution Sequence or Flow of Control 
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As Figure 18-2 shows, most of the input routines execute in a specified sequence. 
This sequence is defined by the symbiont’s main control routine. You cannot 
modify this main control routine; thus, you cannot modify the sequence in which 
symbiont routines are called. 


The input routines that do not execute in sequence are called “demand input 
routines.” These routines are called whenever the service they provide is required 
and include the page header, page setup, and library module input routines. 


The symbiont can perform input, formatting, and output functions 
asynchronously; that is, the order in which the symbiont calls the input, 
formatting, and output routines can vary. For example, the symbiont can 

call an input routine, which returns a record to the input buffer; it can then call 
the format routine, which moves that record to the output buffer; and then it can 
call the output routine to move that data to the printing device. This sequence 
results in the movement of a single data record from disk to printing device. 


On the other hand, the symbiont can call the input and formatting routines 
several times before calling the output routine for a single buffer. The buffer 
can contain one or more formatted input records. In some cases an output buffer 
might contain only a portion of an input record. 
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In this way the symbiont can store input records; then call the format routine, 
which moves one of those records to the output buffer; and finally call the output 
routine, which moves that data to the printing device. Note, however, that the 
formatting routine must be called once for each input record. 


Similarly, the symbiont can store several formatted records before calling the 
output routine to move them to the printing device. 


The symbiont requires this flexibility in altering the sequence in which input, 
format, and output routines are called for reasons of efficiency (high rate of 
throughput) and adaptability to various system parameters and system events. 


The value specified with the call to PSM$PRINT determines the maximum size of 
the symbiont’s output buffer, which cannot be larger than the value of the system 
parameter MAXBUF. If the buffer is very small, the symbiont might need to call 
its output routine one or more times for each record formatted. If the buffer is 
large, the symbiont stores several formatted records before calling the output 
routine to move them to the printing device. 


18.3 Symbiont Modification Procedure 


To modify the print symbiont, perform the following steps. These steps are 
described in more detail in the sections that follow. 


1. Determine the modification needed. The modification might involve changing 
the way the symbiont performs a certain function, or it might involve adding 
a new function. 


2. Determine where to make the modification. This involves selecting a function 
and determining where that function is performed within the symbiont’s 
execution sequence. You specify a function by calling the PSM$REPLACE 
routine and specifying the code that identifies the function. 


Some codes correspond to symbiont-supplied routines. When you specify one 
of these codes, you replace that routine with your routine. Other codes do 
not correspond to symbiont-supplied routines. When you specify one of these 
codes, you add your routine to the set of routines the symbiont executes. 
Table 18-1 lists these codes. 


3. Write the routine. Because the symbiont calls your routine, your routine must 
have one of three call interfaces, depending on whether it is an input, format, 
or output routine. See the descriptions of the USER-INPUT-ROUTINE, 
USER-FORMAT-ROUTINE, and USER-OUTPUT-ROUTINE routines, which 
follow the descriptions of the PSM routines. 


4. Write the symbiont-initialization routine. This routine executes when the 
symbiont is first activated by the job controller. It initializes the symbiont’s 
internal database; specifies, by calling PSM$REPLACE, the routines you have 
supplied; activates the symbiont by calling PSM$PRINT; and performs any 
necessary cleanup operations when PSM$PRINT completes. 


5. Construct the modified symbiont. This involves compiling your routines, then 
linking them. 


6. Integrate the modified symbiont with the system. This involves placing the 
executable image in SYS$SYSTEM, identifying the symbiont image to the job 
controller, and debugging the symbiont. 
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As mentioned previously, you identify each routine you write for the symbiont 
by calling the PSM$REPLACE routine. The code argument for this routine 
specifies the point within the symbiont’s execution sequence at which you want 
your routine to execute. You should know which code you will use to identify 
your routine before you begin to write the routine. Section 18.3.6 provides more 
information about these codes. 


18.3.1 Guidelines and Restrictions 


The following guidelines and restrictions apply to the writing of any symbiont 
routine: 


e Do not use the process-permanent files identified by the logical names 
SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND. 


e The symbiont code should be linked against SMBSRVSHR.EXE in order to 
define the following status codes: 


— PSM$ FLUSH 
— PSM$ FUNNOTSUP 
—- PSM$ PENDING 
—- PSM$ SUSPEND 
— PSM$ EOF 
—- PSM$ BUFFEROVF 
— PSM$ NEWPAGE 
— PSM$ ESCAPE 
— PSM$ INVVMSOSC 
—- PSM$ MODNOTFND 
— PSM$ NOFILEID 
— PSM$ OSCTOOLON 
— PSM$ TOOMANYLEV 
—- PSM$ INVITMCOD 
—- PSM$ LATSYM 
« Do not use the system services $HIBER and $WAKE. 


e The job completion (PSM$K_J OB COMPLETION) and output (PSM$K _ 
OUTPUT) routines are not replaceable when using the LAT protocol option. 


e« Use the following two OpenVMS Run-Time Library routines for allocation and 
deallocation of memory: LIB$GET_VM and LIB$FREE_VM. 


e Minimize the amount of time that your routine spends executing at AST level. 
The job controller sends messages to the symbiont by means of user-mode 
ASTs; the symbiont cannot receive these ASTs while your user routine is 
executing at AST level. 


e The symbiont can call your routines at either AST level or non-AST level. 
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If your routine returns any error-condition value (low bit clear), the symbiont 
aborts the current task and notifies the job controller. Note that, by default, 
an error-condition value returned during the processing of a task causes 

the job controller to abort the entire job. However, this default behavior 

can be overridden. See the description of the /RETAIN qualifier of the DCL 
commands START/QUEUE, INITIALIZE/QUEUE, and SET QUEUE in the 
HP OpenVMS DCL Dictionary. 


The symbiont stores the first error-condition value (low bit clear) returned 
during the processing of a task. The symbiont’s fileerrors routine, an input 
routine (code PSM$K_FILE_ERRORS), places the message text associated 
with this condition value in the symbiont’'s input stream. The symbiont prints 
this text at the end of the listing, immediately before the trailer pages. 


The symbiont sends this error-condition value to the job controller; the job 
controller then stores this condition value with the job record in the job 
controller’s queue file. The job controller also writes this condition value in 
the accounting record for the job. 


If you choose to return a condition value when an error occurs, you should 
choose one from the system message file. This lets system programs access 
the message text associated with the condition value. Specifically, the 
Accounting and SHOW/QUEUE utilities and the job controller will be able to 
translate the condition value to its corresponding message text and to display 
this message text as appropriate. 


This guideline applies to input, input-filter, and output-filter routines, and to 
the symbiont’s use of dynamic string descriptors in these routines. 


The simplest way for an input routine to pass the data record to the symbiont 
is for it to use a Run-Time Library string-handling routine (for example, 
STR$COPY_R). These routines use dynamic string descriptors to point to the 
record they have handled and to copy that record from your input buffer to 
the symbiont-supplied buffer specified in the funcdesc argument. 


By default, the symbiont initializes a dynamic string descriptor that your 
input routine can use to describe the data record it returns. Specifically, the 
symbiont initializes the DSC$B_DTYPE field of the string descriptor with 
the value DSC$K_DTYPE_T (which indicates that the data to which the 
descriptor points is a string of characters) and initializes the DSC$B_ CLASS 
fied with the value DSC$K_CLASS_D (which indicates that the descriptor is 
dynamic). 

Alternatively, the input routine can pass a data record to the symbiont by 
providing its own buffer and passing a static string descriptor that describes 
the buffer. To do this, you must redefine the fields of the descriptor to which 
the funcdesc argument points, as follows: 


1. Initialize the field DSC$B_ CLASS with the value DSC$K_CLASS _ 
S (which indicates that the descriptor points to a scalar value or a 
fixed-length string). 

2. Initialize the field DSC$A_POINTER with the address of the buffer that 
contains the data record. 


3. Initialize the field DSC$W_LENGTH with the length, in bytes, of the data 
record. 
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Each time the symbiont calls the routine to read some data, the symbiont 

reinitializes the descriptor to make it a dynamic descriptor. Consequently, if 
you want to use the descriptor as a static descriptor, your input routine must 
initialize the descriptor each time it is called to perform a reading operation. 


Input-filter routines and output-filter routines return a data record to the 
symbiont by means of the func_desc_2 argument. The symbiont initializes a 
descriptor for this argument the same way it does for descriptors used by the 
input routine. Thus, the guidelines described for the input routine apply to 
the input-filter routine and output-filter routine. 


18.3.2 Writing an Input Routine 


This section provides an overview of the logic used in the print symbiont’s main 
input routine, and it discusses the way in which the print symbiont handles 
carriage-control effectors. 


The print symbiont calls your input routine, supplying it with arguments. Your 
routine must return arguments and condition values to the print symbiont. For 
this reason, your input routine must use the interface described in the description 
of the USER-INPUT-ROUTINE. 


When the print symbiont calls your routine, it specifies a particular request in 
the func argument. Each function has a corresponding code. 


Your routine must provide the functions identified by the codes PSM$K_OPEN, 
PSM$K_READ, and PSM$K_CLOSE. Your routine need not respond to the other 
function codes, but it can if you want it to. If your routine does not provide a 
function that the symbiont requests, it must return the condition value PSM$_ 
FUNNOTSUP to the symbiont. 


The description of the func argument of the USER-INPUT-ROUTINE describes 
the codes that the symbiont can send to an input routine 


See Section 18.3.5 for additional information about other function codes used in 
the user-written input routine. 


For each task that the symbiont processes, it calls some input routines only once, 
and some more than once; it always calls some routines and calls others only 
when needed. 


Table 18-1 lists the codes that you can specify when you call the PSM$REPLACE 
routine to identify your input routine to the symbiont. The description of the 
PSM$REPLACE routine describes these routines. 


18.3.2.1 Internal Logic of the Symbiont’s Main Input Routine 
The internal logic of the symbiont’s main input routine, as described in this 
section, is subject to change without notice. This logic is summarized here. This 
summary is not intended as a tutorial on the writing of a symbiont’s main input 
routine, although it does provide insight into such a task. 


A main input routine is one that the symbiont calls to read data from the file that 
is to be printed. A main input routine must perform three sets of tasks: one set 
when the symbiont calls the routine with an OPEN request, one set when the 
symbiont calls with a READ request, and one set when the symbiont calls with a 
CLOSE request. 
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The following table lists the codes that identify each of these three requests and 
describes the tasks that the symbiont’s main input routine performs for each 


request: 
Code Action Taken by the Input Routine 
PSM$K_OPEN An OPEN request. When the main input routine receives this 


request code, it does the following: 
1. Opens the input file. 
2. Stores information about the input file. 


3. Returns the type of carriage control used in the input file. If 
this routine cannot open the file, it returns an error. 


Note that the print symbiont’s main input routine performs these 
tasks when it receives the PSM$K_START_TASK function code, 
rather than the PSM$K_OPEN function code. 


This atypical behavior occurs because some of the information 
stored by the main input routine must be available for other input 
routines that execute before the main input routine. For example, 
information about file attributes and record formats is needed 

by the symbiont’s separation-page routines, which print flag and 
burst pages. 


Consequently, if you supply your own main input routine, some 
of the information about the file being printed that appears on 
the standard separation pages is not available, and the symbiont 
prints a message on the separation page stating so. 

The symbiont receives the file-identification number from the job 
controller in the SMBMSG$K_FILE_IDENTIFICATION item of 
the requesting message and uses this value rather than the file 
specification to open the main input file. 


PSM$kK_READ A READ request. When the main input routine receives this 
request, it returns the next record from the file. In addition, when 
the carriage control used by the data file is PSM$K_CC_PRINT, 
the main input routine returns the associated record header. 


PSM$K_CLOSE A CLOSE request. When the main input routine receives this 
request, it closes the input file. 


18.3.2.2  Symbiont Processing of Carriage Control 
Each input record can be thought of as consisting of three parts: leading carriage 
control, data, and trailing carriage control. Taken together, these three parts are 
called the composite data record. 


Leading and trailing carriage control are determined by the type of carriage 
control used in the file and explicit carriage-control information returned with 
each record. For embedded carriage control, however, leading and trailing 
carriage control is always null. 


The type of carriage control returned by the main input routine on the PSM$K _ 
OPEN request code determines, for that invocation of the input routine, how 
the symbiont applies carriage control to each record that the main input routine 
returns on the PSM$K_READ request code. 


Note that, for all four carriage control types, the first character returned on the 
first PSM$K_READ call to an input routine receives special processing. If that 
character is a line feed or a form feed and if the symbiont is currently at line 1, 
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column 1 of the current page, then the symbiont discards that line feed or form 
feed. 


The Four Types of Carriage Control 

The following table briefly describes each type of carriage control and how the 
symbiont’s main input routine processes it. For a detailed explanation of each 
type of carriage control, refer to the description of the FAB$B_RAT field of the 
FAB block in the OpenVMS Record Managenet Services Reference Manual. 


Type of Carriage Control Symbiont Processing 


Embedded Leading and trailing carriage control are embedded 
in the data portion of the input record. Therefore, 
the symbiont supplies no special carriage control 
processing; it assumes that leading and trailing 
carriage control are null. 


Fortran The first byte of each data record contains a Fortran 
carriage-control character. This character specifies 
both the leading and trailing carriage control for the 
data record. The symbiont extracts the first byte of 
each data record and interprets that byte as a Fortran 
carriage-control character. If the data record is empty, 
the symbiont generates a leading carriage control of 
line feed and a trailing carriage control of carriage 
return. 


PRN Each data record contains a 2-byte header that 
contains the carriage-control specifier. The first 
byte specifies the carriage control to apply before 
printing the data portion of the record. The second 
byte specifies the carriage control to apply after 
printing the data portion. The abbreviation PRN 
stands for print-file format. 


Unlike other types of carriage control, PRN carriage 
control information is returned through the funcarg 
argument of the main input routine; this occurs with 
the PSM$K_READ request. The funcarg argument 
specifies a longword; your routine writes the 2-byte 
PRN carriage control specifier into the first two bytes 
of this longword. 


Implied The symbiont provides a leading line feed and a 
trailing carriage return. But if the data record consists 
of a single form feed, the symbiont sets to null the 
leading and trailing carriage control for that record, 
and the leading carriage control for the record that 
follows it. 


18.3.3 Writing a Format Routine 


To write a format routine, follow the modification procedure described in 
Section 18.3. Do not replace the symbiont’s main format routine. Instead, 
modify its action by writing input and output filter routines. These execute 
immediately before and after the main format routine, respectively. The main 
formatting routine uses an undocumented and nonpublic interface; you cannot 
replace the main formatting routine. The DCL command PRINT/PASSALL 
bypasses the main format routine of the print symbiont. 


See Section 18.3.5 for additional information about other function codes used in 
the user-written formatting routine. 
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18.3.3.1 Internal Logic of the Symbiont’s Main Format Routine 


The main format routine contains all the logic necessary to convert composite 
data records to a data stream for output. Actions taken by the format routine 
include the following: 


¢ Tracking the current column and line 
e Implementing the special processing of the first character of the first record 


e Implementing the alignment data mask specified by the DCL command 
START/QUEUE/ALIGN=MASK 


¢ Handling margins as specified by the forms definition 


e Initiating processing of page headers when specified by the DCL command 
PRINT/HEADER 


e Expanding leading and trailing carriage control 

e Handling line overflow 

¢« Handling page overflow 

e Expanding tab characters to spaces for some devices 
e« Handling escape sequences 

e Accumulating accounting information 


e Implementing double-spacing when specified by the DCL command 
PRINT/SPACE 


e Implementing automatic page ejection when specified by the DCL command 
PRINT/FEED 


The symbiont’s main format routine uses a special rule when processing the 
first character of the first composite data record returned by an input routine. 
(A composite data record is the input data record and a longword that contains 
carriage-control information for the input data record.) This rule is that if the 
first character is a vertical format effector (form feed or line feed) and if the 
symbiont has processed no printable characters on the current page (that is, 
the current position is column 1, line 1), then that vertical format effector is 
discarded. 


18.3.4 Writing an Output Routine 


To write an output routine, follow the modification procedure described in 
Section 18.3. 


The print symbiont calls your output routine. Input arguments are supplied by 
the print symbiont; output arguments and status values are returned by your 
routine to the print symbiont. For this reason, your output routine must have the 
call interface that is described in the USER-OUTPUT-ROUTINE routine. 


When the print symbiont calls your routine, it specifies in one of the input 
arguments—the func argument—the reason for the call. Each reason has a 
corresponding function code. 


There are several function codes that the print symbiont can supply when it 
calls your output routine. Your routine must contain the logic to respond to the 
following function codes: PSM$K_OPEN, PSM$K_WRITE, PSM$K_WRITE_ 
NOFORMAT, and PSM$K_CLOSE. 
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It is not required that your output routine contain the logic to respond to the 
other function codes, but you can provide this logic if you want to. 


A complete list and description of all relevant function codes for output routines 
is provided in the description of the func argument of the USER-OUTPUT- 
ROUTINE routine. 


See Section 18.3.5 for additional information about other function codes. 


18.3.4.1. Internal Logic of the Symbiont’s Main Output Routine 


When the symbiont calls the main output routine with the PSM$K_ OPEN 
function code, the main output routine takes the following steps: 


1. Allocates the print device 

2. Assigns a channel to the device 
3. Obtains the device characteristics 
4 


Returns the device-status longword in the funcarg argument (for more 
information, see the description of the SMBMSG$K_ DEVICE STATUS 
message item in Chapter 19) 


5. Returns an error if the device is not a terminal or a printer 


When this routine receives a PSM$K_WRITE service request code, it sends the 
contents of the symbiont output buffer to the device for printing. 


When this routine receives a PSM$K_WRITE_NOFORMAT service request code, 
it sends the contents of the symbiont output buffer to the device for printing and 
suppresses device drive formatting as appropriate for the device in use. 


When this routine receives a PSM$K_ CANCEL service request code, it requests 
the device driver to cancel any outstanding output operations. 


When this routine receives a PSM$K_CLOSE service request code, it deassigns 
the channel to the device and deallocates the device. 
18.3.5 Other Function Codes 


A status PSM$ PENDING might not be returned whenever the symbiont notifies 
user-written input, output, and format routines using the following message 
function codes: 


Function Code Description 

PSM$K_START_STREAM J ob controller sends a message to the symbiont to start 
a queue 

PSM$K_START_TASK Symbiont parses a message from job controller 
directing it to start a queue 

PSM$K_PAUSE_TASK J ob controller sends a message to the symbiont to 
suspend processing of the current task 

PSM$K_STOP_STREAM J ob controller sends a message to the symbiont to stop 
the queue 

PSM$K_STOP_TASK J ob controller sends a message to the symbiont to stop 
the task 

PSM$K_RESUME_TASK J ob controller sends a message to the symbiont to 
resume processing of the current task 

PSM$K_RESET_STREAM Same as PSM$K_STOP_STREAM 
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18.3.6 Writing a Symbiont Initialization Routine 


Writing a symbiont initialization routine involves writing a program that calls 
the following: 


1. PSM$REPLACE once for each routine (input, output, or format) that you 
have written. PSM$REPLACE identifies your routines to the symbiont. 


2. PSM$PRINT exactly once after you have identified all your service routines 
using PSM$REPLACE. 


Table 18-1 lists all routine codes that you can specify in the PSM$REPLACE 
routine. Choosing the correct routine code is important because the code specifies 
when the symbiont will call your routine The functions of these routines are 
described further in the description of the PSM$REPLACE routine. 


For those input routines that execute in a predefined sequence, the second column 
contains a number showing the order in which that input routine is called relative 
to the other input routines for a single file job. If the routine does not execute in 
a predefined sequence, the second column contains the character x. 


Column three specifies whether the routine is an input, format, or output routine; 
this information directs you to the section describing how to write a routine of 
that type. 


Column four specifies whether there is a symbiont-supplied routine corresponding 
to that routine code. The codes for the input-filter and output-filter routines, 
which have no corresponding routines in the symbiont, allow you to specify new 
routines for inclusion in the symbiont. 


Table 18-1 Routine Codes for Specification to PSM$REPLACE 


Routine Code Sequence Function Supplied 
PSM$K_J OB_SETUP 1 Input Yes 
PSM$K_FORM_SETUP 2 Input Yes 
PSM$K_J OB_FLAG 3 Input Yes 
PSM$K_J OB_BURST 4 Input Yes 
PSM$kK_FILE_ SETUP 5 Input Yes 
PSM$K_FILE_ FLAG 6 Input Yes 
PSM$kK_FILE_BURST 7 Input Yes 
PSM$K_FILE_SETUP_2 8 Input Yes 
PSM$K_MAIN_INPUT 9 Input Yes 
PSM$kK_FILE_INFORMATION 10 Input Yes 
PSM$kK_FILE_ERRORS 11 Input Yes 
PSM$kK_FILE_ TRAILER 12 Input Yes 
PSM$K_J OB_RESET 13 Input Yes 
PSM$K_J OB_TRAILER 14 Input Yes 
PSM$K_J OB_COMPLETION?* 15 Input Yes 
PSM$K_PAGE_SETUP x Input Yes 


1The job completion (PSM$K_J OB COMPLETION) and output (PSM$K_OUTPUT) routines are not 
replaceable when using the LAT protocol option. 


(continued on next page) 
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Table 18-1 (Cont.) Routine Codes for Specification to PSM$REPLACE 


Routine Code Sequence Function Supplied 
PSM$K_PAGE_ HEADER x Input Yes 
PSM$K_LIBRARY_INPUT x Input Yes 
PSM$K_INPUT_FILTER x Formatting No 
PSM$K_MAIN_FORMAT x Formatting Yes 
PSM$K_OUTPUT_FILTER x Formatting No 
PSM$K_OUTPUT? x Output Yes 


1The job completion (PSM$K_] OB COMPLETION) and output (PSM$K_OUTPUT) routines are not 
replaceable when using the LAT protocol option. 


18.3.7 Integrating a Modified Symbiont 


To integrate your user routine and the symbiont initialization routine, perform 
the following steps; note that the sequence of steps described here assumes that 
you will be debugging the modified symbiont: 


1. 


Compile or assemble the user routine and the symbiont initialization routine 
into an object module. 


Enter the following DCL command: 
$ LINK/DEBUG your-symbiont 


The file name your-symbiont is the object module built in Step 1. Symbols 
necessary for this link operation are located in the shareable images 
SYS$SHARE:SMBSRVSHR.EXE and SYS$LIBRARY:IMAGELIB.EXE. 
The linker automatically searches these shareable images and extracts the 
necessary information. 


Place the resulting executable symbiont image in SYS$SYSTEM. 


Locate two unallocated terminals: one at which to issue DCL commands and 
one at which to debug the symbiont image. 


Log in on one of the terminals under UIC [1,4], which is the system manager’s 
account. This terminal is the one at which you enter DCL commands. Do not 
log in at the other terminal. 


Enter the following DCL command: 
$ SET TERMINAL/NODISCONNECT/PERMANENT TTcu: 


The variable _TTcu: is the physical terminal name of the terminal at which 
you want to debug (the terminal at which you are not logged in). You must 
specify the underscore (_ ) and colon (:) characters. 


Enter the following DCL commands: 


$ DEFINE/GROUP DBGSINPUT TTcu: 
$ DEFINE/GROUP DBGSOUTPUT TTcu: 


The variable TTcu: specifies the physical terminal name of the terminal at 
which you will be debugging. Note that other users having a UIC with group 
number 1 should not use the debugger at the same time. 


Initialize the queue by entering the following DCL command: 
$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /ON= printer name 
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10. 


11. 


The symbiont image specified by the file name your-symbiont must reside in 
SY S$SYSTEM. Note too that the /PROCESSOR qualifier accepts only a file 
name; the device, directory, and file type default to SYS$SYSTEM:.EXE. 


The /ON qualifier specifies the device that will be served by the symbiont 
while you debug the symbiont. 


Enter the following DCL command to execute the modified symbiont routine: 
$ PRINT/HEADER/QUEUE=queue-id 


Enter the following DCL command to start the queue and invoke the 
debugger: 


$ START/QUEUE queue-name 


After you debug your symbiont, relink the symbiont by entering the following 
DCL command: 


$ LINK/NOTRACEBACK/NODEBUG your-symbiont 


Deassign the logical names DBG$INPUT and DBG$OUTPUT so that they 
will not interfere with other users in UIC group 1. 


18.4 Using the PSM Routines: An Example 


Example 18-1 shows how to use PSM routines to supply a page header routine in 
a VAX MACRO program. 


Example 18-1 Using PSM Routines to Supply a Page Header Routine in a VAX MACRO 
Program 


.TITLE EXAMPLE - Example user modified symbiont 
.IDENT ‘V03-000' 


THIS PROGRAM SUPPLIES A USER WRITTEN PAGE HEADER 
ROUTINE TO THE STANDARD SYMBIONT. THE PAGE HEADER 
INCLUDES THE SUBMITTER’S ACCOUNT NAME AND USER NAME, 
THE FULL FILE SPECIFICATION, AND THE PAGE NUMBER. 
THE HEADER LINE IS UNDERLINED BY A ROW OF DASHES 
PRINTED ON A SECOND HEADER LINE. 


.LIBRARY /SYSSLIBRARY:LIB.MLB/ 


System definitions 


$PSMDEF 
SSMBDEF 
$DSCDEF 


; Symbiont definitions 
; Message item definitions 
; Descriptor definitions 


Define argument offsets for user supplied services called by symbiont 


CONTEXT 
WORK_AREA 
FUNC 
FUNC_DESC 
FUNC_ARG 


= 04 ; symbiont context 

= 08 ; user context 

=.12 ; function code 

= 16 ; function dependent descriptor 
= 20 ; function dependent argument 


(continued on next page) 
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Example 18-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a VAX 


r 


, 


1 


a 


, 


r 


START: .WORD 0 


r 


1 


10S: 


MACRO Program 


Macro to create dynamic descriptors 


.MACRO D_DESC 


.WORD 0 
.BYTE DSCSK_DTYPE T 
.BYTE DSCSK CLASS D 
.LONG 0 


. ENDM 


Storage for page header information 


FILE: D_DESC 
USER: D_DESC 
ACCOUNT: D_DESC 
PAGE: .LONG 0 
LINE: .LONG 0 


FAO control string and work buffer. 


DSCSW_LENGTH = 0 
DSCSB_DTYPE = STRING 
DSCS$B_CLASS = DYNAMIC 
DSCSA_POINTER = 0 


file name descriptor 
user name descriptor 
account name descriptor 


page number 
line number 


Header format: 


"Taccount,name] filename ........ Page 9999" 

FAO Ctrl: .ASCID /!71<[!AS, !AS] !AS!>Page 9999/ 

FAO Ctrl 2: .ASCID /!4UL/ 

FAO DESC: -LONG 80 ; work buffer descriptor 
.ADDRESS FAO BUFF 

FAO BUFF: . BLKB 80 ; work buffer 


Own storage for values passed by reference 


CODE: . LONG 0 
STREAMS : . LONG il 
BUFSIZ: . LONG 2048 
LINSIZ: . WORD 81 
Main routine -- invoked at image startup 


Supply private page header routine 


MOVZBL 
PUSHAL 
PUSHAL 
CALLS 
BLBC 


#PSMSK_PAGE HEADER, CODE 
HEADER 

CODE 

#2,G*PSMSREPLACE 

RO, 108 


Transfer control to the standard symbiont 


PUSHAL BUFSIZ 
PUSHAL STREAMS 

CALLS +#2,G*PSMSPRINT 
RET 


service or item code 

number of simultaneous streams 
output buffer size 

line size for underlines 


; save nothing because this routine uses only RO and R1 


service code 

of modified routine 
of service code 

the routine 

any errors 


set the 
address 
address 
replace 
exit if 


address of output buffer size 
address of number of streams 
invoke standard symbiont 


(continued on next page) 
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Example 18-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a VAX 


MACRO Program 


' 


; Page header routine 


HEADER: .WORD 0 


; Check function code 


' 


CMPL PSM$K_START TASK, @FUNC (AP) 
BEQL 208 
CMPL PSM$K_READ, @FUNC (AP) 
BNEQ 15$ 
BRW 508 
158: CMPL PSM$K_OPEN, @FUNC (AP) 
BNEQ 168 
BRW 668 
168: MOVL PSM$_FUNNOTSUP, RO 
RET 


I 


; Starting a new file 


20S: 
CLRL PAGE 
MOVZBL #2,LINE 


; Get the account name 


MOVZBL #SMBMSG$K_ACCOUNT_NAME, CODE 
PUSHAL ACCOUNT 

PUSHAL CODE 

PUSHAL @CONTEXT (AP) 

CALLS  #3,G*PSMSREAD ITEM DX 

BLBC —-RO, 408 


; Get the file name 


MOVZBL #SMBMSGSK_FILE SPECIFICATION, CODE 


PUSHAL FILE 

PUSHAL CODE 

PUSHAL @CONTEXT (AP) 

CALLS  #3,G*PSMSREAD ITEM DX 
BLBC —-RO, 408 


; Get the user name 


MOVZBL #SMBMSG$K_USER_NAME, CODE 
PUSHAL USER 

PUSHAL CODE 

PUSHAL @CONTEXT (AP) 

CALLS  #3,G*PSMSREAD ITEM DX 
BLBC —-RO, 408 
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save nothing 


new task? 
branch if so 
READ function? 


branch if so 
OPEN function? 


branch if so 
unsupported function 
return to symbiont 


reset the page number 
and the line number 


set item code 
address of descriptor 
address of item code 


address of symbiont ctx value 


read it 
branch if any errors 


; set item code 
address of descriptor 
address of item code 


address of symbiont ctx value 


read it 
branch if any errors 


set item code 
address of descriptor 
address of item code 


address of symbiont ctx value 


read it 
branch if any errors 


(continued on next page) 
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Example 18-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a VAX 
MACRO Program 


; Set up the static header information that is constant for the task 


, 


SFAO S CTRSTR = FAO Ctrl, - ; FAO control string desc 
OUTBUF = FAO DESC, - output buffer descriptor 
Pl = #ACCOUNT, - account name descriptor 
P2 = #USER, - user name descriptor 


BLBC RO, 40S branch if any errors 
MOVL #PSMS_FUNNOTSUP, RO unsupported function 
40S: RET return usupported status or error 


; Read a page header 


P3 = #FILE ; file name descriptor 


50S: 
DECL LINE ; decrement the line number 
BEQL 60S ; branch if second read 
BLSS 70S ; branch if third read 


; Insert the page number into the header 


INCL PAGE 

MOVAB FAO BUFF+76,FAO DESC+4 

SFAO S CTRSTR = FAO Ctrl 2, - 
OUTBUF = FAO DESC, - 
Pl = PAGE 

MOVAB FAO BUFF, FAO DESC+4 

BLBC —-RO, 55$ 


increment the page number 
point to page number buffer 
FAO control string desc 
output buffer descriptor 
page number 

point to work buffer 

return if error 


; Copy the line to the symbiont’s buffer 


work buffer descriptor 


PUSHAB FAO DESC 
F symbiont descriptor 


PUSHL UNC DESC (AP) 


CALLS 2,G”*STRSCOPY DX copy to symbiont buffer 
558: RET return success or any error 
; Second line -- underline header 
60S: 
PUSHL FUNC_DESC (AP) ; symbiont descriptor 
PUSHAL LINSIZ ; number of bytes to reserve 
CALLS #2,G“STRSGET1_ DX ; reserve the space 
BLBC RO, 67S ; exit if error 
OVL FUNC_DESC (AP) ,R1 ; get address of descriptor 
OVL 4(R1),R1 ; get address of buffer 
OVAB 80(R1),RO ; set up transfer limit 
65$: OVB #*A/-/, (R1)+ ; fill with dashes 
CMPL RO,R1 ; reached limit? 
BGTRU 65S ; branch if not 
OVB #10, (R1) + ; extra line feed 
66S: OVZBL #SS$ NORMAL, RO ; set success 
678: RET ; return 


(continued on next page) 
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Example 18-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a VAX 
MACRO Program 


' 


; Done with this page header 


70S: 


MOVL #PSMS$_EOF,RO ; return end of input 
MOVZBL #2,LINE ; reset line counter 
RET ; return 

. END START 


18.5 PSM Routines 


This section describes the individual PSM routines. 
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PSM$PRINT—Invoke OpenVMS-Supplied Print Symbiont 


Format 


Returns 


Arguments 


The PSM$PRINT routine invokes the OpenVMS-supplied print symbiont. 


PSM$PRINT must be called exactly once after all user service routines have been 
specified using PSM$REPLACE. 


PSM$PRINT _ [streams] [,bufsiz] [,worksiz] [,maxqios] [,options] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


streams 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Maximum number of streams that the symbiont is to support. The streams 
argument is the address of a longword containing this number, which must be in 
the range of 1 to 16. If you do not specify streams, a default value of 1 is used. 
Thus, by default, a user-modified symbiont supports one stream, which is to say 
that it is a singlethreaded symbiont. 


A stream (or thread) is a logical link between a print execution queue and a 
printing device. When a symbiont process can accept simultaneous links to more 
than one queue, that is, when it can service multiple queues simultaneously, the 
symbiont is said to be multithreaded. 


bufsiz 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Maximum buffer size in bytes that the print symbiont is to use for output 
operations. The bufsiz argument is the address of a longword containing the 
specified number of bytes. 


The print symbiont actually uses a buffer size that is the smaller of: (1) the 
value specified by bufsiz or (2) the system parameter MAXBUF. If you do not 
specify bufsiz, the print symbiont uses the value of MAXBUF. 


The print symbiont uses this size limit only for output operations. Output 
operations involve the placing of processed or formatted pages into a buffer that 
will be passed to the output routine. 
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The print symbiont uses the value specified by bufsiz only as an upper limit; 
most buffers that it writes will be smaller than this value. 


worksiz 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Size in bytes of a work area to be allocated for the use of user routines. The 
worksiz argument is the address of a longword containing this size in bytes. If 
you do not specify worksiz, no work area is allocated. 


A separate area of the specified size is allocated for each active symbiont stream. 


maxqios 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Specifies the maximum number of outstanding $QIOs that a print symbiont 
stream using the LAT protocol may generate. Set symbiont process quotas large 
enough to handle the maximum number of QIOs multiplied by the number of 
streams, using a number between 2 and 32. For normal printing capabilities, the 
suggested quota is 10; for high-speed printing, use a larger number. 


options 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Longword bit vector that specifies the LAT protocal option using the PSM$M _ 
LAT PROTOCOL symbolic value. Note that using the LAT PROTOCOL option 
carries the following restrictions: 


« Replacement of the output and job completion routines will be overridden 
¢ Output device must be a LAT device 


Description 


The PSM$PRINT routine must be called exactly once after all user routines 
have been specified to the print symbiont. Each user routine is specified to the 
symbiont in a call to the PSM$REPLACE routine. 


The PSM$PRINT routine allows you to specify whether the print symbiont is to 
be single-threaded or multithreaded, and if multithreaded, how many streams or 
threads it can have. In addition, this routine allows you to control the maximum 
size of the output buffer. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


This routine also returns any condition values returned by the $SETPRV, 
$GETSYI, $PURGWS, and $DCLAST system services, as well as any condition 
values returned by the SMB$INITIALIZE routine documented in Chapter 19. 
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PSM$READ_ITEM_DX—Obtain Value of Message ltems 


Format 


Returns 


Arguments 


The PSM$READ_ITEM_DxX routine obtains the value of message items that are 
sent by the job controller and stored by the symbiont. 


PSM$READ_ITEM_DX_ request_id ,item ,buffer 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


request_id 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Request identifier supplied by the symbiont to the user routine currently calling 
PSM$READ_ITEM_DX. The symbiont always supplies a request identifier when 
it calls a user routine with a service request. The request_id argument is the 
address of a longword containing this request identifier value. 


Your user routine must copy the request identifier value that the symbiont 
supplies (in the request_id argument) when it calls your user routine. Then, 
when your user routine calls PSM$READ ITEM _Dx, it must supply (in the 
request_id argument) the address of the request identifier value that it copied. 


item 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Item code that identifies the message item that PSM$READ_ITEM_DxX is to 
return. The item argument is the address of a longword that specifies the item’s 
code. 


For a complete list and description of each item code, refer to the documentation 
of the item argument in the SMB$READ_MESSAGE_ITEM routine in 
Chapter 19. 
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buffer 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Buffer into which PSM$READ_ITEM_DxX returns the specified informational 
item. The buffer argument is the address of a descriptor pointing to this buffer. 


The PSM$READ_ITEM_DxX routine returns the specified informational item 
by copying that item to the buffer using one of the STR$COPY_xx routines 
documented in the OpenVMS RTL String Manipulation (STR$) Manual. 


Description 


The PSM$READ_ITEM_DxX routine obtains the value of message items that are 
sent by the job controller and stored by the symbiont. Use PSM$READ_ITEM_ 

DX to obtain information about the task currently being processed, for example, 
the name of the file being printed (SGMBMSG$K_FILE SPECIFICATION) or the 
name of the user who submitted the job (GMBMSG$K_USER_NAME). 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
PSM$ INVITMCOD Invalid item code specified in the item argument. 


This routine also returns any condition values returned by any of the 
STR$COPY_xx routines documented in the OpeVMS RTL String Manipulation 
(STR$) Manual. 
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PSM$REPLACE—Declare User Service Routine 


Format 


Returns 


Arguments 


The PSM$REPLACE routine substitutes a user service routine for a symbiont 
routine or adds a user service routine to the set of symbiont routines. 


You must call PSM$REPLACE once for each routine that you replace or add. 


PSM$REPLACE code ,routine 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


code 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Routine code that identifies the symbiont routine to be replaced by a user service 
routine. The code argument is the address of a longword containing the routine 
code. 


Some routine codes identify routines that are supplied with the symbiont; when 
you specify such a routine code, you replace the symbiont-supplied routine with 
your service routine. 


Two routine codes identify routines that are not supplied with the symbiont; 
when you specify such a routine code, your service routine is added to the set of 
symbiont routines. 


Table 18-1 lists each routine code in the order in which it is called within the 
symbiont execution stream; this table also specifies whether a routine code 
identifies an input, formatting, or output routine and whether the routine is 
supplied with the symbiont. 


Each programming language provides an appropriate mechanism for defining 
these routine codes. The following pages list each routine code in alphabetical 
order; the description of each code includes the following information about its 
corresponding routine: 


e Whether the routine is supplied by the symbiont 
e Whether the routine is an input, formatting, or output routine 
e Under what conditions the routine is called 


e What task the routine performs 
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Routine Codes 


PSM$K_FILE_BURST 

This code identifies a symbiont-supplied input routine; it is called whenever a file 
burst page is requested. This routine obtains information about the job, formats 
the file burst page, and returns the contents of the page to the input buffer. A file 
burst page follows a file flag page and precedes the contents of the file. 


PSM$K_FILE_ERRORS 

This code identifies a symbiont-supplied input routine; it is called when errors 
have occurred during the job. This routine places the error message text in the 
input buffer. 


PSM$K_FILE_FLAG 

This code identifies a symbiont-supplied input routine; it is called whenever a file 
flag page is requested. This routine obtains information about the job, formats 
the file flag page, and returns the contents of the page to the input buffer. A flag 
page follows the job burst page (if any) and precedes the file burst page (if any). 
It contains such information as the file specification of the file and the name of 
the user issuing the print request. 


PSM$K_FILE_INFORMATION 

This code identifies a symbiont-supplied input routine; it is called when the file 
information item has been specified by the job controller. This routine expands 
the file information item to text and returns it to the input buffer. 


PSM$K_FILE_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine queues any specified file-setup modules for insertion in the input stream 
when the PSM$K_FILE_SETUP routine closes. 


PSM$K_FILE_SETUP_2 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine returns a form feed to ensure that printing of the file begins at the top of 
the page. This routine is called just before the main input routine. 


PSM$K_FILE_TRAILER 

This code identifies a symbiont-supplied input routine; it is called whenever a file 
trailer page is requested. This routine obtains information about the job, formats 
the file trailer page, and returns the contents of the page to the input buffer. A 
trailer page follows the last page of the file contents. 


PSM$K_MAIN_FORMAT 

This code identifies the symbiont-supplied formatting routine; it is always called. 
This routine performs numerous formatting functions. You cannot replace this 
routine. 


PSM$K_FORM_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine queues any specified form-setup modules for insertion in the input stream 
when the PSM$K_FORM_SETUP routine closes. 


PSM$K_INPUT_FILTER 

This code identifies a format routine that is not supplied by the symbiont. If 

the routine is supplied by the user, it is always called immediately prior to the 
symbiont-supplied formatting routine (routine code PSM$K_MAIN_ FORMAT). An 
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input-filter service routine is useful for modifying input data records and their 
carriage control before they are formatted by the symbiont. 


PSM$K_JOB_BURST 

This code identifies a symbiont-supplied input routine; it is called whenever a job 
burst page is requested. This routine obtains information about the job, formats 
the job burst page, and returns the contents of the page to the input buffer. A job 
burst page follows the job flag page and precedes the file flag page (if any) of the 
first file in the job. It is similar to a file burst page except that it appears only 
once per job and only at the beginning of the job. 


PSM$K_JOB_COMPLETION 

This code identifies a symbiont-supplied input routine that returns a form feed, 
which causes any output stored by the device to be printed. The routine is always 
called. It cannot be replaced when using the LAT protocol option. 


PSM$K_JOB_FLAG 

This code identifies a symbiont-supplied input routine; it is called whenever a job 
flag page is requested. This routine obtains information about the job, formats 
the job flag page, and returns the contents of the page to the input buffer. A job 
flag page is similar to a file flag page except that it appears only once per job, 
preceding the job burst page (if any). 


PSM$K_JOB_RESET 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine queues any specified job-reset modules for insertion in the input stream 
when the PSM$K_J OB_RESET routine closes. 


PSM$K_JOB_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine checks to see if this is the first job to be printed on the device, and if so, 
it issues a form feed and then performs a job reset. See the description of the 
PSM$K_J OB_RESET routine for information about job reset. 


PSM$K_JOB_TRAILER 

This code identifies a symbiont-supplied input routine; it is called whenever a job 
trailer page is requested. This routine obtains information about the job, formats 
the job trailer page, and returns the contents of the page to the input buffer. A 
job trailer page is similar to a file trailer page except that it appears only once 
per job, as the last page in the job. 


PSM$K_MAIN_INPUT 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine opens the file to be printed, returns input records to the input buffer, and 
closes the file. 


PSM$K_LIBRARY_INPUT 

This code identifies a symbiont-supplied input routine; it is called when an input 
routine closes and when modules have been requested for insertion in the input 
stream. This routine returns the contents of the specified modules, one record per 
call. You cannot replace this routine. 


PSM$K_OUTPUT_FILTER 

This code identifies a formatting routine that is not supplied by the symbiont. If 
the routine is supplied by the user, it is always called. This routine executes prior 
to the symbiont output routine (routine code PSM$K_ OUTPUT). An output-filter 
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Description 


service routine is useful for modifying output data buffers before they are passed 
to the output routine. 


At the point where the output-filter routine executes within the symbiont 
execution stream, the input data is no longer in record format; instead, the data 
exists as a stream of characters. The carriage control, for example, is embedded 
in the data stream. Thus, the output buffer might contain what was once a 
complete record, part of a record, or several records. 


PSM$K_PAGE_HEADER 

This code identifies a symbiont-supplied input routine; it is called once at the 
beginning of each page if page headers are requested. This routine returns to the 
input buffer one or more lines containing information about the file being printed 
and the current page number. This routine is called only while the main input 
routine is open. 


PSM$K_PAGE_SETUP 

This code identifies a symbiont-supplied routine; it is called at the beginning of 
each page if page-setup modules were specified. This routine queues any specified 
page-setup modules for insertion in the input stream when the PSM$K_PAGE _ 
SETUP routine closes. This routine is called only while the main input routine is 
open. 


PSM$K_OUTPUT 

This code identifies the symbiont-supplied output routine that writes the contents 
of the output buffer to the printing device, together with many other functions. 
This routine is always called. It cannot be replaced when using the LAT protocol 
option. 


routine 

OpenVMS usage: procedure 

type: procedure value 
access: read only 
mechanism: by reference 


User service routine that is to replace a symbiont routine or to be included. The 
routine argument is the address of the user routine entry point. 


The PSM$REPLACE routine must be called each time a user service routine 
replaces a symbiont routine or is added to a set of symbiont routines. 


The code argument specifies the symbiont routine to be replaced. The routine 
codes that can be specified in the code argument are of two types: those that 
identify existing print symbiont routines and those that do not. All the routine 
codes are similar, however, in the sense that each supplies a location within the 
print symbiont execution stream where your routine can execute. 


By selecting a routine code that identifies an existing symbiont routine, you 
effectively disable that symbiont routine. The service routine that you specify 
might or might not perform the function that the disabled symbiont routine 
performs. If it does not, the net effect of the replacement is to eliminate that 
function from the list of functions performed by the print symbiont. Exactly what 
your service routine does is up to you. 
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By selecting a routine code that does not identify an existing symbiont routine 
(those that identify the input-filter and output-filter routines), your service 
routine has a chance to execute at the location signified by the routine code. 
Because the service routine you specify to execute at this location does not 
replace another symbiont routine, your service routine is an addition to the set of 
symbiont routines. 


As mentioned, each routine code identifies a location in the symbiont execution 
stream, whether or not it identifies a symbiont routine. Table 18-1 lists each 
routine code in the order in which the location it identifies is reached within the 
symbiont execution stream. 


Condition Value Returned 


SS$ NORMAL Normal successful completion. 
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PSM$REPORT—Report Completion Status 


Format 


Returns 


Arguments 


The PSM$REPORT routine reports to the print symbiont the completion status of 
an asynchronous operation initiated by a user routine. 


Such a user routine must return the completion status PSM$ PENDING. 
PSM$REPORT must be called exactly once for each time a user routine returns 
the status PSM$ PENDING. 


PSM$REPORT _ request_id [,status] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


request_id 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Request identifier supplied by the symbiont to the user routine at the time the 
symbiont called the user routine with the service request. The user routine must 
return the completion status PSM$ PENDING on the call for this service request. 
The request_id argument is the address of a longword containing the request 
identifier value. 


The symbiont calls the user routine with a request code that specifies the function 
that the symbiont expects the user routine to perform. In the call, the symbiont 
also supplies a request identifier, which serves to identify the request. If the 
user routine initiates an asynchronous operation, a mechanism is required for 
notifying the symbiont that the asynchronous operation has completed and for 
providing the completion status of the operation. 


The PSM$REPORT routine conveys the above two pieces of information. In 
addition, PSM$REPORT returns to the symbiont (in the request_id argument) 
the same request identifier value as that supplied by the symbiont to the user 
routine that initiated the operation. In this way, the symbiont synchronizes the 
completion status of an asynchronous operation with that invocation of the user 
routine that initiated the operation. 


Any user routine that initiates an asynchronous operation must, therefore, 
copy the request identifier value that the symbiont supplies (in the request_id 
argument) when it calls the user routine. The user routine will later need to 
supply this value to PSM$REPORT. 
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In addition, when the user routine returns, which it does before the asynchronous 
operation has completed, the user routine must return the status PSM$_ 
PENDING. 


status 

OpenVMS usage: cond_value 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Completion status of the asynchronous operation that has completed. The status 
argument is the address of a longword containing this completion status. The 
status argument is optional; if it is not specified, the symbiont assumes the 
completion status SS$ NORMAL. 


The user routine that initiates the asynchronous operation must test for the 
completion of the operation and must supply the operation’s completion status 
as the status argument to the PSM$REPORT routine. The Description section 
describes this procedure in greater detail. 


If the completion status specified by status has the low bit clear, the symbiont 
aborts the task. 


An asynchronous operation is an operation that, once initiated, executes “off 

to the side” and need not be completed before other operations can begin to 
execute. Asynchronous operations are common in symbiont applications because 
a symbiont, if it is multithreaded, must handle concurrent I/O operations. 


One example of a user routine that performs an asynchronous operation is 

an output routine that calls the $QIO system service to write a record to the 
printing device. When the user output routine completes execution, the |/O 
request queued by $QIO might not have completed. In order to synchronize this 
1/O request, that is, to associate the I/O request with the service request that 
initiated it, you should use the following mechanism: 


1. In making the call to $QIO, specify the astadr and iosb arguments. The 
astadr argument specifies an AST routine to execute when the queued output 
request has completed, and the iosb argument specifies an |/O status block 
to receive the completion status of the |/O operation. Step 3 describes some 
functions that your AST routine will need to do. 


2. Have the user output routine return the status PSM$ PENDING. 
3. Write the AST routine to perform the following functions: 


a. Copy the completion status word from the I/O status block to a longword 
location that you will specify as the status argument in the call to 
PSM$RE PORT. 


b. Call PSM$REPORT. Specify as the request_id argument the request 
identifier that was supplied by the print symbiont in the original call to 
the user output routine. 
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Condition Value Returned 


SS$ NORMAL Normal successful completion. 
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USER-FORMAT-ROUTINE—Invoke User-Written Format Routine 


Format 


Returns 


Arguments 


The user-written USER-FORMAT-ROUTINE performs format operations. The 
symbiont’s control logic routine calls your format routine at one of two possible 
points within the symbiont’s execution stream. You select this point by specifying 
one of two routine codes when you call the PSM$REPLACE routine. 


A user format routine can be an input filter routine (routine code PSM $K _ 
INPUT FILTER) or an output filter routine (routine code PSM$K_ OUTPUT _ 
FILTER). The main format routine (routine code PSM$K_ MAIN FORMAT) 
cannot be replaced. 


A user format routine must use the call interface described here. 


USER-FORMAT-ROUTINE  request_id ,work_area ,func ,func_desc_1 ,func_arg_1 
func_desc_2 ,func_arg_2 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


request_id 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Request identifier supplied by the symbiont when it calls your format routine. 
The request_id argument is the address of a longword containing this request 
identifier value. 


work_area 

OpenVMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Work area supplied by the symbiont for the use of your format routine. The 
symbiont supplies the address of this area when it calls your routine. The work_ 
area argument is a longword containing the address of the work area. The work 
area is a section of memory that your format routine can use for buffering and 
other internal operations. 


The size of the work area allocated is specified by the work_size argument in the 
PSM$PRINT routine If you do not specify work_size in the call to PSM$PRINT, 
no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each thread. 
This work area is shared by all user routines. The work area is initialized to zero 
when the symbiont is first started. 


func 

OpenVMS usage: function_code 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Function code specifying the service that the symbiont expects your format 
routine to perform. The func argument is the address of a longword into which 
the symbiont writes this function code. 


The function code specifies the reason the symbiont is calling your format routine 
or, in other words, the service that the symbiont expects your routine to perform 
at this time. 


The PSM$K_ FORMAT function code is the only one to which your format routine 
must respond. When the symbiont calls your format routine with this function 
code, your routine must move a record from the input buffer to the output buffer. 


The symbiont can call your format routine with other function codes. Your routine 
should return the status PSM$ FUNNOTSUP (function not supported) when it 
is called with any of the following function codes or with any undocumented 
function code. When the status PSM$ FUNNOTSUP is returned, the symbiont 
performs its normal action as if no format routine were supplied. To suppress the 
symbiont’s normal action, you should return SS$ NORMAL. 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_ STREAM 


These function codes correspond to message items, which are discussed in more 
detail in Section 18.3.5, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are not 
part of the public interface to the print symbiont. 


Your format routine should return the status PSM$ FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 


function code. 

func_desc_1 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Descriptor supplying an input record to be processed by the format routine. 
The func_desc_1 argument is the address of a string descriptor. By using this 
argument, the symbiont supplies the input record that your format routine 

is to process. Because this descriptor can be of any valid string type, your 
format routine should use the Run-Time Library string routines to analyze this 
descriptor and to manipulate the input record. 
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func_arg_1 

OpenVMS usage: vector_byte unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


Carriage control for the input record supplied by func_desc_1. The func_arg 1 
argument is the address of a 4-byte vector that specifies the carriage control for 
the input record. The following diagram depicts the format of this 4-byte vector: 


31 23 15 7 0 
Trailing Carriage—Control Leading Carriage—Control 
Information Information 
ZK-2009-GE 


Bytes 0 and 1 describe the leading carriage control to apply to the input data 
record; bytes 2 and 3 describe the trailing carriage control. 


Byte 0 is anumber specifying the number of times the carriage control specifier 
in byte 1 is to be repeated preceding the input data record. Byte 2 is a number 
specifying the number of times the carriage control specifier in byte 3 is to be 
repeated following the input data record. 


For values of the carriage control specifier from 1 to 255, the specifier is the 
ASCII character to be used as carriage control. Value 0 represents the ASCII 
“newline” sequence. Newline consists of a carriage return followed by a linefeed. 


The func_arg_1 argument is not used if your format routine is an output filter 
routine (routine code PSM$K_ OUTPUT FILTER). See the Description section for 
more information. 


func_desc 2 
OpenVMS usage: char_string 


type: character string 
access: write only 
mechanism: by reference 


Descriptor of a buffer to which your format routine writes the formatted output 
record. The func_desc_2 argument is the address of a string descriptor. 


Your format routine must return the formatted data record by using the func_ 
desc_2 argument. 


Your format routine should use the Run-Time Library string routines to write 
into the buffer specified by this descriptor. 


func_arg 2 

OpenVMS usage: vector_byte unsigned 
type: byte (unsigned) 
access: write only 
mechanism: by reference 


Carriage control for the output record returned in func_desc_2. The func_arg 2 
argument is the address of a 4-byte vector that specifies the carriage control for 
the output record. See the description of func_arg_1 for the contents and format 
of this 4-byte vector. 
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Description 


If you do not process the carriage-control information supplied in func_arg_1, 
then you should copy that value into func_arg 2. Otherwise, the carriage-control 
information will be lost. 


The func_arg_2 argument is not used if your format routine is an output filter 
routine (routine code PSM$K_OUTPUT FILTER). See the Description section 
help topic for more information. 


When used, the func_arg_1 argument describes carriage-control information for 
the input data record, and the func_arg_2 argument describes carriage-control 
information for the output data record. 


The input data record is passed to the format routine (input filter or output filter) 
for processing, and the output data record is returned by the format routine 
(input filter or output filter). 


One of the tasks performed by the main format routine (routine code PSM$K _ 
MAIN FORMAT) is that of embedding the carriage-control information (specified 
by func_arg_1) into the data record (specified by func_desc_1). Thus, the output 
data (specified by func_desc_2) contains embedded carriage control and is thus 
no longer in record format; it is, therefore, properly referred to as an output data 
stream rather than an output data record. 


Similarly, the output filter routine (routine code PSM$K_OUTPUT_FILTER), 
which executes after the main format routine, uses neither the func_arg_1 nor 
func_arg_2 argument; the data it receives (via func_desc_1) and the data it 
returns (via func_desc_2) are data streams, not data records. 


However, the input filter routine (routine code PSM$K_INPUT_FILTER), which 
executes before the main format routine, uses both func_arg_1 and func_arg_2. 
This is so because the main format routine has not yet executed, and so the 
carriage control information has not yet been embedded in the data record. 


Condition Values Returned 


SS$ NORMAL Successful completion. The user format routine 
has completed the function that the symbiont 
requested. 

PSM$ FUNNOTSUP Function not supported. The user format routine 


does not support or does not recognize the 
function code supplied by the symbiont. To 
ensure future compatibility, your format routine 
should return this status for any unrecognized 
status codes. 


This routine also returns any error condition values that you have coded your 
format routine to return. Refer to Section 18.3.1 for more information about error 
condition values. 
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USER-INPUT-ROUTINE—Invoke User-Written Input Routine 


The user-written USER-INPUT-ROUTINE performs input operations. The 
symbiont calls your routine at a specified point in its execution stream; you 
specify this point using the PSM$REPLACE routine. 


Format 
USER-INPUT-ROUTINE request_id ,work_area ,func ,funcdesc ,funcarg 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
request_id 
OpenVMS usage: address 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Request identifier value supplied by the symbiont when it calls your input 
routine. The request_id argument is the address of a longword containing this 
request identifier value. 


If your input routine initiates an asynchronous operation (for example, a call to 
the $QIO system service), your input routine must copy the request identifier 
value specified by request_id because this value must later be passed to the 
PSM$REPORT routine. See the description of the PSM$REPORT routine for 
more information. 


work_area 

OpenVMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Work area supplied by the symbiont for the use of your input routine. The 
symbiont supplies the address of this area when it calls your routine. The work_ 
area argument is a longword into which the symbiont writes the address of the 
work area. The work area is a section of memory that your input routine can use 
for buffering and for other internal operations. 


The size of the work area allocated is specified by the work_size argument in the 
PSM$PRINT routine If you do not specify work_size in the call to PSM$PRINT, 
no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each thread. 
This work area is shared by all user routines. The work area is initialized to zero 
when the symbiont is first started. 


func 

OpenVMS usage: function_code 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Function code supplied by the symbiont when it calls your input routine. The 
func argument is the address of a longword containing this code. 


The function code specifies the reason the symbiont is calling your input routine 
or, in other words, the function that the symbiont expects your routine to perform 
at this time. 


Most function codes require or allow additional information to be passed in the 
call by means of the funcdesc and funcarg arguments. The description of each 
input function code, therefore, includes a description of how these two arguments 
are used with that function code. 


Following is a list of all the function codes that the symbiont can specify when 
it calls your input routine (function codes applicable only to format and output 
routines are explained in the descriptions of the USER-FORMAT-ROUTINE and 
USER-OUTPUT-ROUTINE, respectively); all function codes are defined by the 
$PSMDEF macro. 


Function Codes for Input Routines 


PSM$K_CLOSE 
When the symbiont calls your routine with this function code, your routine must 
terminate processing by releasing any resources it might have allocated. 


The symbiont calls your routine with PSM$K_ CLOSE when (1) your routine 
returns from a PSM$K_READ function call with the status PSM$ EOF (end of 
input) or with any error condition, or (2) the symbiont receives a task-abortion 
request from the job controller. 


In any event, the symbiont always calls your input routine with PSM$K_CLOSE 
if your routine returns successfully from a PSM$K_OPEN function call. This 
guaranteed behavior ensures that any resources your routine might have 
allocated on the OPEN will be released on the CLOSE. 


PSM$K_GET_KEY 

Typically, the use of both the PSM$K_GET_KEY and PSMK$K_POSITION_TO_ 
KEY function codes is appropriate only for a main input routine (routine code 
PSM$K_MAIN_INPUT). 


When the symbiont calls your routine with this function code, your routine can 
do one of two things: (1) return PSM$ FUNNOTSUP (function not supported) or 
(2) return an input marker string to the symbiont. 


If your routine returns PSM$ FUNNOTSUP to this function code, then your 
routine must also return PSM$ FUNNOTSUP if the symbiont subsequently calls 
your routine with the PSM$K_POSITION_TO_KEY function code. By returning 
PSM$ FUNNOTSUP, your routine is choosing not to respond to the symbiont 
request. 
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If your routine chooses to respond to the PSM$K_GET_KEY function code, your 
routine must return an input marker string to the symbiont; this input marker 
string identifies the input record that your input routine most recently returned 
to the symbiont. Subsequently, when the symbiont calls your input routine with 
the PSM$K_POSITION_TO_KEY function code, the symbiont passes your input 
routine one of the input marker strings that your input routine has returned on 
a previous PSM$K_GET_KEY function call. Using this marker string, your input 
routine must position itself so that, on the next PSM$K_READ call from the 
symbiont, your input routine will return (or reread) the input record identified by 
the marker string. 


Coding your input routine to respond to PSM$K_GET_KEY and 
PSM$K_POSITION_TO_KEY allows the modified symbiont to 

perform the file-positioning functions specified by the DCL commands 
START/QUEUE/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP_OF _ 
FILE, START/QUEUE/SEARCH, and START/QUEUE/BACK WARD. These file 
positioning functions also depend on the job controller’s checkpointing capability 
for print jobs. 


Note that your input routine might be called with a marker string that was 
originally returned in a different process context from the current one. This can 
occur because marker strings are sometimes stored in the queue-data file across 
system shutdowns or different invocations of your symbiont. 


The funcdesc argument specifies the address of a string descriptor. Your routine 
must return the marker string by way of this argument. HP recommends that 
you use one of the Run-Time Library string routines to copy the marker string to 
the descriptor. 


The symbiont periodically calls your input routine with the PSM$K_GET_ KEY 
function code when the symbiont wants to save a marker to a particular input 
record. 


PSM$K_OPEN 

When the symbiont calls your routine with this function code, your routine should 
prepare for input operations by performing such tasks as allocating necessary 
resources, initializing storage areas, opening an input file, and so on. Typically, 
the next time the symbiont calls your input routine, the symbiont will specify the 
PSM$K_READ function code. Note, however, that under some circumstances the 
symbiont might follow an OPEN call immediately with a CLOSE call. 


The funcdesc argument points to the name of the file to be opened. Your routine 
can use this file specification or the file identification to open the file. 


The funcarg argument specifies the address of a longword. Your input routine 
must return, in this longword, the carriage control type that is to be applied to 
the input records that your input routine will provide. 


The symbiont formatting routine requires this information to determine where to 
apply leading and trailing carriage control characters to the input records that 
your input routine will provide. 
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The $PSMDEF macro defines the following four carriage control types: 


Carriage Control Type Description 


PSM$K_CC_IMPLIED Implied carriage control. For this type, the 
symbiont inserts a leading line feed (LF ) and 
trailing carriage return (CR) in each input record. 
This is the default carriage control type; it is used 
if your routine does not supply a carriage control 
type in the funcarg argument in response to the 
PSM$K_OPEN function call. 


PSM$K_CC FORTRAN Fortran carriage control. For this type, the 
symbiont extracts the first byte of each input record 
and interprets the byte as a Fortran carriage control 
character, which it then applies to the input record. 


PSM$K_CC PRINT PRN carriage control. For this type, the symbiont 
generates carriage control from a 2-byte record 
header that your input routine supplies, with each 
READ call, in the funcarg argument. The funcarg 
argument specifies the address of a longword to 
receive this 2-byte header record, which appears 
only in PRN print files. 

PSM$K_CC_INTERNAL Embedded carriage control. For this type, the 
symbiont supplies no carriage control to input 
records. Carriage control is assumed to be 
embedded in the input records. 


PSM$K_POSITION_TO_KEY 

When the symbiont calls your routine with this function code, your routine must 
locate the point in the input stream designated by the marker string that your 
routine returned to the symbiont on the PSM$K_GET_KEY function call. 


The next time the symbiont calls your routine, the symbiont specifies the PSM $K 
READ function call, expecting to receive the next sequential input record. After 
rereading this record, subsequent READ calls proceed from this new position of 
the file. This is not a onetime rereading of a single record but a repositioning 
of the file. The symbiont calls your routine with this function code when the job 
controller receives a request to resume printing at a particular page. 


Refer to the description of the PSM$K_GET_KEY for more information. 


PSM$K_READ 

When the symbiont calls your routine with this function code, your routine must 
return an input record. The symbiont repeatedly calls your input routine with 
the PSM$K_READ function code until: (1) your routine indicates end of input by 
returning the status PSM$ EOF, (2) your routine or another routine returns an 
error status, or (3) the symbiont receives an asynchronous task-abortion request 
from the job controller. 


The funcdesc argument specifies the address of a string descriptor. Your routine 
must return the input record by using this argument. HP recommends that you 
use one of the Run-Time Library string routines to copy the input record to the 
descriptor. 
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The funcarg argument specifies the address of a longword. This argument is 
used only if the carriage control type returned by your input routine on the 
PSM$K_OPEN function call was PSM$K_CC_PRINT. In this case, your input 
routine must supply, in the funcarg argument, the 2-byte record header found at 
the beginning of each input record. 


PSM$K_REWIND 

When the symbiont calls your routine with this function code, your routine must 
do one of two things: (1) return PSM$ FUNNOTSUP (function not supported) or 
(2) locate the point in the input stream designated as the beginning of the file. 


If your routine returns PSM$ FUNNOTSUP to this function code, then 

the symbiont subsequently calls your input routine with a PSM$K_CLOSE 
function call followed by a PSM$K_OPEN function call. By returning PSM$_ 
FUNNOTSUP, your routine is choosing not to support the repositioning of the 
input service to the beginning of the file: The symbiont, therefore, performs the 
desired function by closing and then reopening the input routine. 


You cannot use the funcdesc and the funcarg arguments with this function 
code. 


This function call allows the modified symbiont to perform the file 
positioning functions specified by the DCL commands START/QUEUE/TOP__ 
OF_FILE, START/QUEUE/FORWARD, START/QUEUE/BACK WARD, 
START/QUEUE/SEARCH, and START/QUEUE/ALIGN. This is a required 
repositioning of the file. 


Other Input Function Codes 

The symbiont can call your input routine with other function codes. Your routine 
must return the status PSM$ FUNNOTSUP (function not supported) when it 

is called with any of the following function codes or with any undocumented 
function code. When the status PSM$ FUNNOTSUP is returned, the symbiont 
performs its normal action as if no input routine were supplied. To suppress the 
symbiont’s normal action, you should return SS$¢ NORMAL. 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_STREAM 


These function codes correspond to message items, which are discussed in detail 
in Section 18.3.5, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are not 
part of the public interface to the print symbiont. 


Your input routine should return the status PSM$ FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 
function code. 


funcdesc 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Function descriptor supplying information related to the function specified by the 
func argument. The funcdesc argument is the address of this descriptor. 
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The contents of the function descriptor can vary for each function. Refer to 
the description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Function argument supplying information related to the function specified by the 
func argument. The funcarg argument is the address of a longword containing 
this function argument. This argument can be an input or an output argument, 

depending on the function request, but is usually used as an output argument. 


Condition Values Returned 


SS$ NORMAL Successful completion. The user input routine 
has completed the function that the symbiont 
requested. 

PSM$ FLUSH Flush output stream. The user input routine 


can return this status only when called with the 
PSM$K_READ function code. When this status 
is returned to the symbiont, the symbiont stops 
calling the input routine with the PSM$K_READ 
function code until all outstanding format and 
output operations have completed. 


PSM$ FUNNOTSUP Function not supported. The user input routine 
does not support or does not recognize the 
function code supplied by the symbiont. To 
ensure future compatibility, your input routine 
should return this status for any unrecognized 
status codes. 


PSM$ PENDING Requested function accepted but not completed. 
Your input routine can return this status only 
with the PSM$K_READ function call. Further, if 
your routine returns PSM$ PENDING, your 
routine must eventually signal completion 
via the PSM$REPORT routine. Refer to the 
description of the PSM$REPORT routine for 
more information about asynchronous operations 
and the PSM$ PENDING condition value. 


This routine also returns any error condition values that you have coded your 
format routine to return. Refer to Section 18.3.1 for more information about error 
condition values. 
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USER-OUTPUT-ROUTINE—Invoke User-Written Output Routine 


Format 


Returns 


Arguments 


The user-written USER-OUTPUT-ROUTINE performs output operations. You 
supply a user output routine by calling the PSM$REPLACE routine with the 
routine code PSM$K_OUTPUT. 


USER-OUTPUT-ROUTINE  request_id ,work_area ,func ,funcdesc ,funcarg 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


request_id 

OpenVMS usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Request identifier value supplied by the symbiont when it calls your output 
routine) The request_id argument is the address of a longword containing this 
value. 


If your output routine initiates an asynchronous operation (for example, a 

call to the $QIO system service), you must save the request_id argument 
because you will need to store the request identifier value for later use with the 
PSM$REPORT routine. See the description of the PSM$REPORT routine for 
more information. 


work_area 

OpenVMS usage: address 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Work area supplied by the symbiont for the use of your format routine. The 
symbiont supplies the address of this area when it calls your routine. The work_ 
area argument is a longword containing the address of the work area. The work 
area is a section of memory that your format routine can use for buffering and 
other internal operations. 


The size of the work area allocated is specified by the work_size argument in the 
PSM$PRINT routine If you do not specify work_size in the call to PSM$PRINT, 
no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each thread. 
This work area is shared by all user routines. The work area is initialized to zero 
when the symbiont is first started. 


func 

OpenVMS usage: function_code 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Function code supplied by the symbiont when it calls your output routine. The 
func argument is the address of a longword containing this code. 


The function code specifies the reason the symbiont is calling your output routine 
or, in other words, the function that the symbiont expects your routine to perform 
at this time. 


Most function codes require or allow additional information to be passed in the 
call via the funcdesc and funcarg arguments. The description of each output 
function code, therefore, includes a description of how these two arguments are 
used for that function code. 


The following list describes all the function codes that the symbiont might supply 
when it calls your output routine (function codes applicable only to input and 
formatting routines are explained in the descriptions of the user input routine 
and user formatting routine, respectively). Each programming language provides 
an appropriate mechanism for defining these function codes. 


Function Codes for Output Routines 


PSM$K_OPEN 

When the symbiont calls your output routine with this function code, your routine 
should prepare to move data to the device by performing such tasks as allocating 
the device, assigning a channel to the device, and so on. The next time the 
symbiont calls your output routine, the symbiont specifies one of the WRITE 
function codes (PSM$K_WRITE or PSM$K_WRITE_NOFORMAT). 


The symbiont calls your output routine with the PSM$K_OPEN function code 
when the symbiont receives the SMBMSG$K_START_ STREAM message from the 
job controller. 


If your output routine returns an error condition value (low bit clear) to the 
PSM$K_OPEN function call, the job controller stops processing on the stream 
and reports the error to whomever entered the DCL command START/QUEUE. 


The funcdesc argument is the address of a descriptor that identifies the name of 
the device to which the output routine is to write. This device name is established 
by the DCL command I NITIALIZE/QUEUE/ON =device 


The funcarg argument is the address of a longword into which the user output 
routine returns the device status longword. Your output routine sets bits in the 
device status longword to indicate to the job controller whether the device falls 
into one of the following categories: 


¢ Can print lowercase letters 
« Is aterminal 
e [Is connected to the CPU by means of a modem (remote) 
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If your output routine does not set any of these bits in the device status longword, 
the job controller assumes, by default, that the device is a line printer that prints 
only uppercase letters. 


PSM$K_WRITE 

When the symbiont calls your routine with this function code, your routine 

must write data to the device. The symbiont supplies the data to be written in 
the funcdesc argument. HP recommends that you use one of the Run-Time 
Library string routines to access the data in the buffer described by the funcdesc 
argument. 


PSM$K_WRITE_NOFORMAT 

When the symbiont calls your routine with this function code, your routine must 
write data to the device and must indicate to the device driver that the data is 
not to be formatted. 


The symbiont calls your routine with this function code when: (1) the print 
request specifies the PASSALL option or (2) data is introduced by the ANSI DCS 
(device control string) escape sequence. 


The symbiont supplies the data to be written in the funcdesc argument. HP 
recommends that you use one of the Run-Time Library string routines to move 
the data from the descriptor to the device. 


The output routine of the symbiont informs the device driver not to format the 
data in the following way: 


e When the device is a line printer, the symbiont’s output routine specifies the 
1O0$ WRITEPBLK function code when it calls the $QIO system service. 


e When the device is a terminal, the symbiont’s output routine specifies the 
1O0$M_NOFORMAT function modifier when it calls the $QIO system serivce. 


PSM$K_CANCEL 
When the symbiont calls your routine with this function code, your routine must 
abort any outstanding asynchronous |/O requests. 


The output routine supplied by the symbiont aborts outstanding I/O requests by 
calling the $CANCEL system service with the 1|O$ CANCEL function code. 


If your output routine returned the condition value PSM$ PENDING to one or 
more previous write requests that are still outstanding (that is, PSM$REPORT 
has not yet been called to report completion), then your output routine must 
call PSM$REPORT one time for each outstanding write request that is canceled 
with this call. That is, canceling an asynchronous write request does not relieve 
the user output routine of the requirement to call PSM$REPORT once for each 
asynchronous write request. 


You cannot use the funcdesc and funcarg arguments with this function code. 
PSM$K_CLOSE 
When the symbiont calls your routine with this function code, your output routine 


must terminate processing and release any resources it allocated (for example, 
channels assigned to the device). 


You cannot use the funcdesc and funcarg arguments with this function code. 
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Other Output Function Codes 

The symbiont can call your output routine with other function codes. Your routine 
should return the status PSM$ FUNNOTSUP (function not supported) when it 
is called with any of the following function codes or with any undocumented 
function code. When the status PSM$ FUNNOTSUP is returned, the symbiont 
performs its normal action as if no output routine were supplied. To suppress the 
symbiont’s normal action, you should return SS$ NORMAL. 


PSM$K_START_STREAM PSM$K_STOP_STREAM 
PSM$K_START_TASK PSM$K_PAUSE_TASK 
PSM$K_RESUME_TASK PSM$K_STOP_TASK 


PSM$K_RESET_ STREAM 


These function codes correspond to message items, which are discussed in more 
detail in Section 19.1.6, sent by the job controller to the symbiont. 


Other function codes correspond to internal symbiont mechanisms that are not 
part of the public interface to the print symbiont. 


Your output routine should return the status PSM$ FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 


function code. 

funcdesc 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Function descriptor supplying information related to the function specified by the 
func argument. The funcdesc argument is the address of this descriptor. 


The contents of the function descriptor can vary for each function. Refer to 
the description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 


funcarg 

OpenVMS usage: user_arg 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Function argument supplying information related to the function specified by the 
func argument. The funcarg argument is the address of a longword containing 
this function argument. 


The contents of the function argument can vary for each function. Refer to 
the description of each function code to determine the contents of the function 
argument. In some cases, the function argument is not used. 
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SS$ NORMAL 


PSM$ FUNNOTSUP 


PSM$ PENDING 
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Normal successful completion. The user output 
routine has completed the function that the 
symbiont requested. 


Function not supported. The user output routine 
does not support or does not recognize the 
function code supplied by the symbiont. To 
ensure future compatibility, your output routine 
should return this status for any unrecognized 
status codes. 


Requested function accepted but not completed. 
Your output routine can return this status only 
with PSM$K_WRITE and PSM$K_WRITE_ 
NOFORMAT function calls. Further, if your 
routine returns PSM$ PENDING, your routine 
must eventually signal completion by way 

of the PSM$REPORT routine. Refer to the 
description of the PSM$REPORT routine for 
more information about asynchronous write 
operations and the PSM$ PENDING condition 
value. 


This routine also returns any error condition values that you have coded your 
output routine to return. Refer to Section 18.3.1 for more information about error 


condition values. 
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Symbiont/Job Controller Interface (SMB) 


Routines 


The Symbiont/] ob Controller Interface (SMB) routines provide the interface 
between the job controller and symbiont processes. A user-written symbiont must 
use these routines to communicate with the job controller. 


19.1 Introduction to SMB Routines 


Always use the SMB interface routines or the $SNDJ BC or $GETQUI system 
services to communicate with the job controller. You need not and should not 
attempt to communicate directly with the job controller. 


To write your own symbiont, you need to understand how symbionts work and, in 
particular, how the standard print symbiont behaves. 


19.1.1 Types of Symbiont 
There are two types of symbiont: 


Device symbiont, either an input symbiont or an output symbiont. An input 
symbiont is one that transfers data from a slow device to a fast device, for 
example, from a card reader to a disk. A card-reader symbiont is an input 
symbiont. An output symbiont is one that transfers data from a fast device 
to a slow device, for example, from a disk to a printer or terminal. A print 
symbiont is an output symbiont. 


Server symbiont, a symbiont that processes or transfers data but is not 
associated with a particular device; one example is a symbiont that transfers 
files across a network. 


The operating system does not supply any server symbionts. 


19.1.2 Symbionts Supplied with the Operating System 
The operating system supplies two symbionts: 


SYS$SYSTEM:PRTSMB.EXE (PRTSMB for short), an output symbiont for 
use with printers and printing terminals 


PRTSMB performs such functions as inserting flag, burst, and trailer pages 
into the output stream; reading and formatting input files; and writing 
formatted pages to the printing device. 


You can modify PRTSMB using the Print Symbiont Modification (PSM) 
routines. 


SYS$SYSTEM:INPSMB.EXE (INPSMB for short), an input symbiont for use 
with card readers 
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This symbiont handles the transferring of data from a card reader to a disk 
file. You cannot modify INPSMB, nor can you write an input symbiont using 
the SMB routines. 


19.1.3 Symbiont Behavior in the OpenVMS Environment 


In the OpenVMS environment, a symbiont is a process under the control of the 
job controller that transfers or processes data. 


Figure 19-1 depicts the components that take part in the handling of user 
requests that involve symbionts. This figure shows two symbionts: (1) the print 
symbiont supplied by the operating system, PRTSMB, and (2) a user-written 
symbiont, GRAPHICS.EXE, which services a graphics plotter. The numbers in 
the figure correspond to the numbers in the list that follows. 


This list does not reflect the activities that must be performed by the hypothetical, 
user-written symbiont, GRAPHICS.EXE. This symbiont is represented in the 
figure to illustrate the correspondence between a user-written symbiont and the 
print symbiont supplied by the operating system. 


Although SMB routines can be used for a different kind of symbiont, many 
of their arguments and associated symbols have names related to the print 
symbiont. The print symbiont is presented here as an example of a typical 
symbiont and illustrates points that are generally true for symbionts. 


Figure 19-1 Symbionts in the OpenVMS Environment 
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@ You request a printing job with the DCL command PRINT. DCL calls the 
$SNDJ BC system service, passing the name of the file to be printed to the 
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job controller, along with any other information specified by qualifiers for the 
PRINT command. 


® The job controller places the print request in the appropriate queue and 
assigns the request a job number. 


© The job controller breaks the print job into a number of tasks (for example, 
printing three copies of the same file is three separate tasks). The job 
controller makes a separate request to the symbiont for each task. 


Each request that the job controller makes consists of a message. Each 
message consists of a code that indicates what the symbiont is to do and a 
number of items of information that the symbiont needs to carry out the task 
(the name of the file, the name of the user, and so on). 


PRTSMB interprets the information it receives from the job controller. 


4) 

@ PRTSMB locates and opens the file it is to print by using the fileidentification 
number the job controller specified in the start-task message. 

6 


PRTSMB sends the data from the file to the printer's driver. 
@ The device driver sends the data to the printer. 


19.1.4 Writing a Symbiont 


Writing your own symbiont permits you to use the queuing mechanisms and 
control functions of the job controller. You might want to do this if you need a 
symbiont for a device that cannot be served by PRTSMB (or a modified form 
of PRTSMB) or if you need a server symbiont. The interface between the job 
controller and the symbiont permits the symbiont you write to use the many 
features of the job controller. 


For example, when you use the DCL command PRINT, the job controller sends 
a message to the print symbiont telling it to print the file. However, when a 
user-written symbiont receives the same message (caused by entering a PRINT 
command), it might interpret it to mean something quite different. A robot 
symbiont, for example, might interpret the message as a command for movement 
and the file specification (specified with the PRINT command) might be a file 
describing the directions in which the robot is to move. 


Note 


Modifying PRTSMB is easier than writing your own symbiont; choose 
this option if possible. The Print Symbiont Modification (PSM) routines 
describe how to modify PRTSMB to suit your needs. 


19.1.5 Guidelines for Writing a Symbiont 


Although you can write a symbiont to use the queuing mechanisms and other 
features of the job controller in whatever way you want, you must follow these 
guidelines to ensure that your symbiont works correctly: 


e The symbiont must not use any of the process-permanent channels, which are 
assigned to the following logical names: 


- SYS$INPUT 
- SYS$OUTPUT 
- SYS$ERROR 
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- SYS$COMMAND 


« The symbiont must allocate and deallocate memory using the Run-Time 
Library (RTL) routines LIB$GET_VM and LIB$FREE_VM. 


¢ To be compatible with future releases of the operating system, you should 
write the symbiont to ignore unknown message-item codes and unknown 
message-request codes. (See the SMB$READ_ITEM_MESSAGE routine.) 


e The symbiont must communicate with the job controller by using the SMB 
routines, the $SNDJ BC system service, and the $GETQUI system service. 


e Thesymbiont should not perform lengthy operations within the context of an 
AST routine. The symbiont can only receive messages from the job controller 
when it is not executing within the context of an AST routine. 


e« The symbiont code should be linked against SMBSRVSHR.EXE in order to 
define the SMB routine address and the following status codes: 


—- SMB$ INVSTMNBR 
—- SMB$ INVSTRLEV 
—- SMB$ NOMOREITEMS 


e Toassign a symbiont to a queue after it is compiled and linked, the executable 
image of the symbiont must reside in SYS$SYSTEM, and you must enter 
either of the following commands: 


INITIALIZE/QUEUE/PROCESSOR=symbiont_filename 


START/QUEUE/PROCESSOR=symbiont_filename 


You should specify only the file name in the command. The disk and directory 
default to SYS$SYSTEM, and all fields except the file name are ignored. 


¢« To help debug symbionts, you should define the logical names DBG$I NPUT 
and DBG$OUTPUT in the LNM$GROUP_000001 logical name table to point 
to your debugging terminal. 


19.1.6 The Symbiont/Job Controller Interface Routines 


The five SMB routines form a public interface to the job controller. The job 
controller delivers requests to symbionts by means of this interface, and the 
symbionts communicate their responses to those requests through this interface. 
A user-written symbiont uses the following routines to exchange messages with 
the job controller: 
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Routine Description 


SMBSINITIALIZE Initializes the SMB facility's internal database, 
establishes the interface to the job controller, and 
defines whether: 


e Messages from the job controller are to be 
delivered to the symbiont synchronously or 
asynchronously with respect to execution of 
the symbiont. 


e The symbiont is to be single-threaded or 
multithreaded; these concepts are described 
in the sections that follow. 


SMB$CHECK_FOR_MESSAGE Checks to see if a message from the job 
controller to the symbiont has arrived (used 
with synchronous symbionts) 

SMB$READ_MESSAGE Reads the job controller’s message into a buffer 


SMB$READ_MESSAGE_ITEM Returns one item of information from the job 
controller’s message (which can have several 
informational items) 


SMB$SEND_TO_J OBCTL Sends a message from the symbiont to the job 
controller 


The following sections discuss how to use the SMB routines when writing your 
symbiont. 


19.1.7 Choosing the Symbiont Environment 


The first SMB routine that a symbiont must call is the SMB$INITIALIZE routine. 
In addition to allocating and initializing the SMB facility’s internal database, it 
offers you two options for your symbiont environment: (1) synchronous or 
asynchonous delivery of messages from the job controller, and (2) single streaming 
or multistreaming the symbiont. 


19.1.7.1 Synchronous Versus Asynchronous Delivery of Requesis 
When you initialize your symbiont/job controller interface, the symbiont 
has the option of accepting requests from the job controller sychronously or 
asynchronously. 


Synchronous Environment 


The address of an AST routine is an optional argument to the SMB$INITIALIZE 
routine; if it is not specified, the symbiont receives messages from the job 
controller synchronously. A symbiont that receives messages synchronously 
must call SMB$CHECK_ FOR_MESSAGE periodically during the processing of 
tasks in order to ensure the timely delivery of STOP_TASK, PAUSE TASK, and 
RESET_STREAM requests. 


SMB$CHECK_FOR_MESSAGE checks to see if a message from the job controller 
is waiting. If a message is waiting, SMB$CHECK FOR MESSAGE returns 

a success code. The caller of SMB$CHECK_FOR_MESSAGE can then call 
SMB$READ_ MESSAGE to read the message and take the appropriate action. 


If no message is waiting, SMB$CHECK_FOR_MESSAGE returns a zero in RO. 
The caller of SMB$CHECK_FOR_MESSAGE can continue to process the task at 
hand. 
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Figure 19-2 is a flowchart for a synchronous, single-threaded symbiont. The 

flowchart does not show all the details of the logic the symbiont needs and does 
not show how the symbiont handles PAUSE_TASK, RESUME_TASK, or RESET_ 
STREAM requests. 


Figure 19-2 Flowchart for a Single-Threaded, Synchronous Symbiont 
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Asynchronous Environment 
To receive messages asynchronously, a symbiont specifies a message-handling 
AST routine as the second argument to the SMB$INITIALIZE routine. In this 


scheme, whenever the job controller sends messages to the symbiont, the AST 
routine is called. 


The AST routine is called with no arguments and returns no value. You have 
the option of having the AST routine read the message within the context of its 
execution or of having the AST routine wake a suspended process to read the 
message outside the context of the execution of the AST routine. 


SMB-6 Symbiont/Job Controller Interface (SMB) Routines 


Symbiont/Job Controller Interface (SMB) Routines 
19.1 Introduction to SMB Routines 


Be aware that an AST can be delivered only while the symbiont is not executing 
within the context of an AST routine. Thus, in order to ensure delivery of 
messages from the job controller, the symbiont should not perform lengthy 
operations at the AST level. 


This is particularly important to the execution of STOP_TASK, PAUSE TASK, 
and RESET STREAM requests. If a STOP_TASK request cannot be delivered 
during the processing of a task, for example, it is useless. 


One technique that ensures delivery of STOP and PAUSE requests in an 
asynchronous environment is to have the AST routine set a flag if it reads a 
PAUSE _ TASK, STOP_TASK, or a RESET STREAM request and to have the 
symbiont’s main routine periodically check the flag. 


Figure 19-3 and Figure 19-4 show flowcharts for a single-threaded, asynchronous 
symbiont. The figures do not show many details that your symbiont might 
include, such as a call to the $QIO system service. 


Note that the broken lines in Figure 19-3 that connect the calls to $HIBER with 
the AST routine’s calls to $WAKE show that the next action to take place is the 
call to $WAKE. They do not accurately represent the flow of control within the 
symbiont but represent the action of the job controller in causing the AST routine 
to execute. 


Symbiont/Job Controller Interface (SMB) Routines SMB-7 


Symbiont/Job Controller Interface (SMB) Routines 
19.1 Introduction to SMB Routines 


Figure 19-3 Flowchart for a Single-Threaded, Asynchronous Symbiont (MAIN Routine) 
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Figure 19-4 Flowchart for a Single-Threaded, Asynchronous Symbiont (AST Routine) 
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19.1.7.2 Single-Streaming Versus Multistreaming 
A single-stream (or thread) is a logical link between a queue and a symbiont 


process. When a symbiont process is linked to more than one queue and serves 
those queues simultaneously, it is called a multithreaded symbiont. 


The argument to the SMB$READ MESSAGE routine provides a way for 

a multithreaded symbiont to keep track of the stream referred to by a 
request. Writing your own multithreaded symbiont, however, can be a complex 
undertaking. 
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19.1.8 Reading Job Controller Requests 


The seven general functions that the job controller can request of the symbiont 
are as follows: 


* SMBMSG$K_START_STREAM 
* SMBMSG$K_STOP_STREAM 
* SMBMSG$K_START_TASK 

* SMBMSG$K_PAUSE_TASK 

* SMBMSG$K_RESUME_TASK 
* SMBMSG$K_STOP_TASK 

* SMBMSG$K_RESET_STREAM 


The job controller passes these requests to the symbiont in a structure that 
contains: (1) a code that identifies the requested function and (2) optional items 
of information that the symbiont might need to perform the requested function. 


By calling SMB$READ MESSAGE, the symbiont reads the function code and 
writes the associated items of information, if any, into a buffer. The symbiont 
then parses the message items stored in the buffer by calling the SMB$READ_ 
MESSAGE_ITEM routine) SMB$READ_MESSAGE_ITEM reads one message 
item each time it is called. 


Each message item consists of a code that identifies the type of information the 
item contains, and the information itself. For example, the SMBMSG$K_J OB_ 
NAME code tells the symbiont that the item contains a string, which is the name 
of a job. 


The number of message items in a request message varies with each type of 
request. Therefore, to ensure that all message items are read, SMB$READ _ 
MESSAGE_ITEM must be called repeatedly for each request. SMB$READ_ 
MESSAGE_ITEM returns status SMB$ NOMOREITEMS after it has read the 
last message item in a given request. 


Typically, a symbiont checks the code of a message item against a case table and 
stores the message string in an appropriate variable until all the message items 
are read and the processing of the request can begin. 


See the description of the SMB$READ_MESSAGE_ITEM routine for a table that 
shows the message items that make up each type of request. 


19.1.9 Processing Job Controller Requests 


After a request is read, it must be processed. The way a request is processed 
depends on the type of request. The following section lists, for each request that 
the job controller sends to the print symbiont, the actions that the standard 
symbiont (PRTSMB) takes when the message is received. These actions are 
oriented toward print symbionts in particular but can serve as a guideline for 
other kinds of symbionts as well. 


The symbiont you write can respond to requests in a similar way or in a different 
way appropriate to the function of your symbiont. HP suggests that your routines 
follow the guidelines described in this document. (Note that the behavior of the 
standard symbiont is subject to change without notice in future versions of the 
operating system.) 
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SMBMSG$K_START_STREAM 


Reset all stream-specific information that might have been altered by previous 
START_STREAM requests on this stream (for multithreaded symbionts). 


Read and store the message items associated with the request. 
Allocate the device specified by the SMBMSG$K_DEVICE_NAME item. 
Assign a channel to the device. 

Obtain the device characteristics. 


If the device is neither a terminal nor a printer, then abort processing and 
return an error to the job controller by means of the SMB$SEND_TO_ 

J OBCTL routine. Note that, even though an error has occurred, the stream 
is still considered started. The job controller detects the error and sends a 
STOP_STREAM request to the symbiont. 


Set temporary device characteristics suited to the way the symbiont will use 
the device. 


For remote devices (devices connected to the system by means of a modem), 
establish an AST to report loss of the carrier signal. 


Report to the job controller that the request has been completed and that the 
stream is started, by specifying SMBMSG$K_START_STREAM in the call to 
SMB$SEND_TO J OBCTL. 


SMBMSG$K_START_TASK 


Reset all task-specific information that might have been altered by previous 
START_TASK requests on this stream number. 


Read and store the message items associated with the request. 
Open the main input file. 


Report to the job controller that the task has been started by specifying 
SMBMSG$K_START_TASK in the call to the SMB$SEND_TO_J OBCTL 
routine. 


Begin processing the task. 


When the task is complete, notify the job controller by specifying 
SMBMSG$K_TASK_ COMPLETE in the call to the SMB$SEND_TO_J OBCTL 
routine. 


SMBMSG$K_PAUSE_TASK 


Read and store the message items associated with the request. 


Set a flag that will cause the main processing routine to pause at the 
beginning of the next output page. 


When the main routine pauses, notify the job controller by specifying 
SMBMSG$K_PAUSE_TASK in the call to the SMB$SEND_TO J OBCTL 
routine. 
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SMBMSG$K_RESUME_TASK 


Read and store the message items associated with the request. 
Perform any positioning functions specified by the message items. 


Clear the flag that causes the main input routine to pause, and resume 
processing the task. 


Notify the job controller that the task has been resumed by specifying 
SMBMSG$K_RESUME_TASK in the call to the SMB$SEND_TO J OBCTL 
routine. 


SMBMSG$K_STOP_TASK 


Read and store the message items associated with the request. 
If processing of the current task has paused, then resume it. 
Cancel any outstanding I/O operations. 

Close the input file. 


If the job controller specified, in the START_TASK message, that a trailer 
page should be printed when the task is stopped or if it specified that the 
device should be reset when the task is stopped, then perform those functions. 


Notify the job controller that the task has been stopped abnormally by 
specifying SMBMSG$K_STOP_TASK and by specifying an error vector in 
the call to SMB$SEND_TO_J OBCTL. PRTSMB specifies the value passed by 
the job controller in the SMBMSG$K_STOP_CONDITION item as the error 
condition in the error vector. 


SMBMSG$K_STOP_STREAM 


Read and store the message items associated with the request. 


Release any stream-specific resources: (1) deassign the channel to the device, 
and (2) deallocate the device. 


Notify the job controller that the stream has been stopped by specifying 
SMBMSG$K_STOP_STREAM in the call to SMB$SEND_TO J OBCTL. 


If this is a single-threaded symbiont or if this is a multithreaded symbiont but 
all other streams are currently stopped, then call the $E XIT system service 
with the condition code SS$¢ NORMAL. 


SMBMSG$K_RESET_STREAM 


Read and store the message items associated with the request. 


Abort any task in progress—you do not need to notify the job controller that 
the task has been aborted, but you may do so if you want. 


If the job controller specified, in the START _TASK message, that a trailer 
page should be printed when the task is stopped or if it specified that 
the device should be reset when the task is stopped, then suppress those 
functions. 


The job controller sends the symbiont a RESET STREAM request to regain 
control of a queue or a device that has failed to respond to a STOP_TASK 
request. The RESET STREAM request should avoid any further I/O activity 
if possible. The printer might be disabled, for example, and requests for 
output on that device will never be completed. 
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e Continue as if this were a STOP_STREAM request. 


Note 


A STOP_STREAM request and a RESET_ STREAM request each stop the 
queue; but a RESET STREAM request is an emergency stop and is used, 
for example, when the device has failed. A RESET_STREAM request 
should prevent any further I/O activity because the printer might not be 
able to complete it. 


19.1.10 Responding to Job Controller Requests 


The symbiont uses the SMB$SEND_TO_J OBCTL routine to send messages to the 
job controller. 


Most messages that the symbiont sends to the job controller are responses to 
requests made by the job controller. Such messages inform the job controller 
that the request has been completed successfully or unsuccessfully. The function 
code that the symbiont returns to the controller in the call to SMB$SEND_TO_ 
J OBCTL indicates what request has been completed. 


For example, if the job controller sends a START_TASK request using the 
SMBMSG$K_START_TASK code, the symbiont responds by calling SMB$SEND_ 
TO_J OBCTL using SMBMSG$K_START_TASK as the request argument to 
indicate that task processing has begun. Until the symbiont responds, the DCL 
command SHOW QUEUE indicates that the queue is starting. 


The responses to some requests use additional arguments to send more 
information than just the request code. See the SMB$SEND_TO_J OBCTL 
routine for a table showing the additional arguments allowed in response to each 
request. 


In addition to sending messages in response to requests, the symbiont can send 
other messages to the job controller. |n these messages the symbiont sends either 
the SMBMSG$K_TASK_COMPLETE code, indicating that it has completed a 
task, or SMBMSG$K_TASK_STATUS, indicating that the message contains 
information on the status of a task. 


Note that, when a START_TASK request is delivered, the symbiont responds with 
a SMB$SEND_TO_J OBCTL message with the SMBMSG$K_START_TASK code. 
This response means the task has been started. It does not mean the task has 
been completed. When the symbiont completes the task, it calls SMB$SEND_TO_ 
J OBCTL with the SMBMSG$K_TASK_ COMPLETE code. 


19.2 SMB Routines 


This section describes the individual SMB routines. 
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SMB$CHECK_FOR_MESSAGE—Check for Message from Job 
Controller 


The SMB$CHECK_FOR_MESSAGE routine determines whether a message sent 
from the job controller to the symbiont is waiting to be read. 


Format 
SMB$CHECK_FOR_MESSAGE 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
None. 
Description 


When your symbiont calls the SMB$INITIALIZE routine to initialize the interface 
between the symbiont and the job controller, you can choose to have requests from 
the job controller delivered by means of an AST. If you choose not to use ASTS, 
your symbiont must call SMB$CHECK_FOR_MESSAGE during the processing of 
tasks in order to see if a message from the job controller is waiting to be read. If 
a message is waiting, SMB$CHECK FOR MESSAGE returns a success code; if 
not, it returns a zero. 


If a message is waiting, the symbiont should call SMB$READ MESSAGE to read 
it to determine if immediate action should be taken (as in the case of STOP_ 
TASK, RESET STREAM or PAUSE_TASK). 


If a message is not waiting, SMB$CHECK_ MESSAGE returns a zero. If this 
condition is detected, the symbiont should continue processing the request at 
hand. 

Condition Values Returned 


SS$ NORMAL One or more messages waiting. 
0 No messages waiting. 
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SMBSINITIALIZE—nitialize User-Written Symbiont 


Format 


Returns 


Arguments 


The SMB$INITIALIZE routine initializes the user-written symbiont and the 
interface between the symbiont and the job controller. It allocates and initializes 
the internal databases of the interface and sets up the mechanism that is to wake 
up the symbiont when a message is received. 


SMB$INITIALIZE — structure_level [,ast_routine] [,streams] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


structure_level 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Version of the symbiont/job controller interface. The structure_level argument 
is the address of a longword containing the version of the symbiont/job controller 
interface used when the symbiont was compiled. Always place the value of the 
symbol SMBMSG$K_STRUCTURE_LEVEL in the longword addressed by this 
argument. Each programming language provides an appropriate mechanism for 
defining symbols. 


ast_routine 

OpenVMS usage: ast_procedure 
type: procedure value 
access: read only 
mechanism: by reference 


Message-handling routine called at AST level. The ast_routine argument is the 
address of the entry point of the message-handling routine to be called at AST 
level when the symbiont receives a message from the job controller. The AST 
routine is called with no parameters and returns no value. If an AST routine is 
specified, the routine is called once each time the symbiont receives a message 
from the job controller. 


The AST routine typically reads the message and determines if immediate action 
must be taken. Be aware that an AST can be delivered only while the symbiont 
is operating at non-AST level. Thus, to ensure delivery of messages from the job 
controller, the symbiont should not perform lengthy operations at AST level. 


If you do not specify the ast_routine argument, the symbiont must call the 
SMB$CHECK_FOR_MESSAGE routine to check for waiting messages. 
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SMBSINITIALIZE 
streams 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Maximum number of streams the symbiont is to support. The streams argument 
is the address of a longword containing the number of streams that the symbiont 
is to Support. The number must be in the range of 1 to 32. 


If you do not specify this argument, a default value of 1 is used. Thus, by default, 
a symbiont supports one stream. Such a symbiont is called a single-threaded 
symbiont. 


A stream (or thread) is a logical link between a queue and a symbiont. 
When a symbiont is linked to more than one queue, and serves those queues 
simultaneously, it is called a multithreaded symbiont. 

Description 


Your symbiont must call SMB$INITIALIZE before calling any other SMB 
routines. It calls SMB$INITIALIZE in order to do the following: 


e Allocate and initialize the SMB facility’s internal database. 

e Establish the interface between the job controller and the symbiont. 

e Determine the threading scheme of the symbiont. 

e Set up the mechanism to wake your symbiont when a message is received. 
After the symbiont calls SMB$INITIALIZE, it can communicate with the job 
controller using the other SMB routines. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
SMB$_ INVSTRLEV Invalid structure level. 


This routine also returns any codes returned by $ASSIGN and LIB$GET_VM. 
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SMB$READ_MESSAGE—Obtain Message Sent by Job Controller 


Format 


Returns 


Arguments 


The SMB$READ_ MESSAGE routine copies a message that the job controller has 
sent into the caller’s specified buffer. 


SMB$READ_MESSAGE stream ,buffer ,request 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


stream 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


Stream number specifying the stream to which the message refers. The stream 
argument is the address of a longword into which the job controller writes the 
number of the stream referred to by the message. In single-threaded symbionts, 
the stream number is always 0. 


buffer 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Address of the descriptor that points to the buffer into which the job controller 
writes the message. SMB$READ_ MESSAGE uses the Run-Time Library string- 
handling (STR$) routines to copy the message into the buffer you supply. The 
buffer should be specified by a dynamic string descriptor. 


request 

OpenVMS usage: identifier 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Code that identifies the request. The request argument is the address of a 
longword into which SMB$READ_ MESSAGE writes the code that identifies the 
request. 
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There are seven request codes. Each code is interpreted as a message by the 
symbiont. The codes and their descriptions follow: 


SMBMSG$K_START_STREAM Initiates processing on an inactive symbiont 
stream. The job controller sends this 
message when a START/QUEUE or an 
INITIALIZE/QUEUE/START command is 
issued on a stopped queue. 


SMBMSG$K_STOP_STREAM Stops processing on a started queue. The 
job controller sends this message when a 
STOP/QUEUE/NE XT command is issued, 
after the symbiont completes any currently 
active task. 


SMBMSG$K_RESET_STREAM Aborts all processing on a started stream 
and requeues the current job. The job 
controller sends this message when a 
STOP/QUEUE/RESET command is issued. 


SMBMSG$K_START_TASK Requests that the symbiont begin processing 
a task. The job controller sends this message 
when a file is pending on an idle, started 
queue. 


SMBMSG$K_STOP_TASK Requests that the symbiont abort the 
processing of a task. The job controller sends 
this message when a STOP/QUEUE/ABORT 
or STOP/QUEUE/REQUEUE command 
is issued. The item SMBMSG$K_STOP_ 
CONDITION identifies whether this is an 
abort or a requeue request. 


SMBMSG$K_PAUSE_ TASK Requests that the symbiont pause in the 
processing of a task but retain the resources 
necessary to continue. The job controller 
sends this message when a STOP/QUEUE 
command is issued without the /ABORT, 
/ENTRY, /REQUEUE, or /NEXT qualifier for 
a queue that is currently printing a job. 


SMBMSG$K_RESUME_TASK Requests that the symbiont continue 
processing a task that has been stopped 
with a PAUSE TASK request. This message 
is sent when a START/QUEUE command is 
issued for a queue served by a symbiont that 
has paused in processing the current task. 


Description 


Your symbiont calls SMB$READ MESSAGE to read a message that the job 
controller has sent to the symbiont. 


Each message from the job controller consists of a code identifying the function 
the symbiont is to perform and a number of message items. There are seven 
codes. Message items are pieces of information that the symbiont needs to carry 
out the requested function. 


For example, when you enter the DCL command PRINT, the job controller sends 
a message containing a START_TASK code and a message item containing the 
specification of the file to be printed. 
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SMB$READ MESSAGE writes the code into a longword (specified by the 
request argument) and writes the accompanying message items, if any, into a 
buffer (specified by the buffer argument). 


See the description of the SMB$READ_MESSAGE_ITEM routine for information 
about processing the individual message items. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


LIB$ INVARG Routine completed unsuccessfully because of an 
invalid argument. 


This routine also returns any of the condition codes returned by the Run-Time 
Library string-handling (STR$) routines. 
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SMB$READ_MESSAGE_ITEM—Parse Next Item from Message 
Buffer 


The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled in by 
the SMB$READ_ MESSAGE routine, parses one message item from the buffer, 
writes the item’s code into a longword, and writes the item into a buffer. 


Format 
SMB$READ_MESSAGE_ITEM message ,context ,item_code ,buffer [,size] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
message 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Message items that SMB$READ_MESSAGE_ITEM is to read. The message 
argument is the address of a descriptor of a buffer. The buffer is the one that 
contains the message items that SMB$READ_ MESSAGE ITEM is toread. The 
buffer specified here must be the same as that specified with the call to the 
SMB$READ_MESSAGE routine, which fills the buffer with the contents of the 


message. 

context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value initialized to 0 specifying the first message item in the buffer to be read. 
The context argument is the address of a longword that the SMB$READ_ 
MESSAGE _ITEM routine uses to determine the next message item to be 
returned. When this value is 0, it indicates that SMB$READ_MESSAGE _ 
ITEM is to return the first message item. 


The SMB$READ_MESSAGE_ITEM routine updates this value each time it reads 
a message item. SMB$READ_MESSAGE_ITEM sets the value to 0 when it has 
returned all the message items in the buffer. 
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item_code 

OpenVMS usage: smb_item 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Item code specified in the message item that identifies its type. The item_code 
argument is the address of a longword into which SMB$READ_MESSAGE_ITEM 
writes the code that identifies which item it is returning. 


The codes that identify message items are defined at the end of the Description 
section for this routine. 


buffer 

OpenVMS usage: char_string 
type: character string 
access: write only 
mechanism: by descriptor 


Message item. The buffer argument is the address of a descriptor of a buffer. 
The buffer is the one in which the SMB$READ_MESSAGE_ITEM routine is to 
place the message item data. SMB$READ_MESSAGE_ITEM uses the Run-Time 
Library string-handling (STR$) routines to copy the message item data into the 
buffer. 


size 

OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Size of the message item. The size argument is the address of a word in which 
the SMB$READ_ MESSAGE _ITEM is to place the size, in bytes, of the item’s 
data. 


The job controller can request seven functions from the symbiont. They are 
identified by the following codes: 


SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 
SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 
SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 


SMBMSG$K_RESET_STREAM 


The job controller passes the symbiont a request containing a code and, optionally, 
a number of message items containing information the symbiont might need to 
perform the function. The code specifies what function the request is for, and 
the message items contain information that the symbiont needs to carry out the 
function. 


By calling SMB$READ_ MESSAGE, the symbiont reads the request and writes 
the message items into the specified buffer. The symbiont then obtains the 
individual message items by calling the SMB$READ MESSAGE _ITEM routine. 


Each message item consists of a code that identifies the information the item 
represents, and the item itself. For example, the SMB$K_J OB_NAME code tells 
the symbiont that the item specifies a job’s name. 


Symbiont/Job Controller Interface (SMB) Routines SMB-21 


Symbiont/Job Controller Interface (SMB) Routines 
SMB$READ_MESSAGE_ITEM 


The number of items in a request varies with each type of request. Therefore, 
you must call SMB$READ MESSAGE _ITEM repeatedly for each request to 
ensure that all message items are read. Each time SMB$READ_MESSAGE _ 
ITEM reads a message item, it updates the value in the longword specified by 
the context argument. SMB$READ_MESSAGE_ITEM returns the code SMB$_ 
NOMOREITEMS after it has read the last message item. 


The following table shows the message items that can be delivered with each 


request: 
Request Message Item 
SMBMSG$K_START_TASK SMBMSG$K_ACCOUNT_ NAME 


SMBMSG$K_AFTER_TIME 
SMBMSG$K_BOTTOM_MARGIN 
SMBMSG$K_CHARACTERISTICS 
SMBMSG$K_CHECKPOINT_DATA 
SMBMSG$K_ENTRY_NUMBER 
SMBMSG$K_FILE_COPIES 
SMBMSG$K_FILE_COUNT 
SMBMSG$K_FILE_IDENTIFICATION 
SMBMSG$K_FILE_SETUP_MODULES 
SMBMSG$K_FILE_SPECIFICATION 
SMBMSG$K_FIRST_PAGE 
SMBMSG$K_FORM_LENGTH 
SMBMSG$K_FORM_NAME 
SMBMSG$K_FORM_SETUP_MODULES 
SMBMSG$K_FORM_WIDTH 
SMBMSG$K_J OB_COPIES 
SMBMSG$K_J OB_COUNT 
SMBMSG$K_J OB NAME 
SMBMSG$K_J OB RESET_MODULES 
SMBMSG$K_LAST_PAGE 
SMBMSG$K_LEFT_MARGIN 
SMBMSG$K_MESSAGE_VECTOR 
SMBMSG$K_NOTE 
SMBMSG$K_PAGE_SETUP_MODULES 
SMBMSG$K_PARAMETER _1 


SMBMSG$K_PARAMETER_8 
SMBMSG$K_PRINT_CONTROL 
SMBMSG$K_SEPARATION_CONTROL 
SMBMSG$K_REQUEST_CONTROL 
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Request Message Item 


SMBMSG$K_PRIORITY 
SMBMSG$K_QUEUE 
SMBMSG$K_RIGHT_MARGIN 
SMBMSG$K_TIME_QUEUED 
SMBMSG$K_TOP_MARGIN 
SMBMSG$K_UIC 
SMBMSG$K_USER_NAME 


SMBMSG$K_STOP_TASK SMBMSG$K_STOP_CONDITION 
SMBMSG$K_PAUSE_TASK None 
SMBMSG$K_RESUME_TASK SMBMSG$K_ALIGNMENT_PAGES 


SMBMSG$K_RELATIVE_PAGE 
SMBMSG$K_REQUEST_CONTROL 
SMBMSG$K_SEARCH_ STRING 

SMBMSG$K_START_STREAM = SMBMSG$K_DEVICE_NAME 
SMBMSG$K_EXECUTOR_QUEUE 
SMBMSG$K_J OB_RESET_ MODULES 
SMBMSG$K_LIBRARY_SPECIFICATION 

SMBMSG$K_STOP_STREAM None 

SMBMSG$K_RESET_STREAM — None 


The following list describes each item code. For each code, the list describes 
the contents of the message item identified by the code and whether the code 
identifies an item sent from the job controller to the symbiont or from the 
symbiont to the job controller. 


Many of the codes described are specifically oriented toward print symbionts. The 
symbiont you implement, which might not print files or serve an output device, 
need not recognize all these codes. In addition, it need not respond in the same 
way as the print symbiont to the codes it recognizes. The descriptions in the list 
describe how the standard print symbiont (PRTSMB.EXE) processes these items. 


Note 


Because new codes might be added in the future, you should write your 
symbiont so that it ignores codes it does not recognize. 


Codes for Message Items 


SMBMSG$K_ACCOUNT_NAME 
This code identifies a string containing the name of the account to be charged for 
the job, that is, the account of the process that submitted the print job. 


SMBMSG$K_AFTER_TIME 
This code identifies a 64-bit, absolute-time value specifying the system time after 
which the job controller can process this job. 
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SMBMSG$K_ALIGNMENT_PAGES 
This code identifies a longword specifying the number of alignment pages that the 
symbiont is to print. 


SMBMSG$K_BOTTOM_MARGIN 
This code identifies a longword containing the number of lines to be left blank at 
the bottom of a page. 


The symbiont inserts a form feed character into the output stream if it determines 
that all of the following conditions are true: 


e The number of lines left at the bottom of the page is equal to the value in 
SMBMSG$K_BOTTOM_MARGIN. 


e« Sending more data to the printer to be output on this page would cause 
characters to be printed within this bottom margin of the page. 


e The/FEED qualifier was specified with the PRINT command that caused the 
symbiont to perform this task. 


(Line feed, form feed, carriagereturn, and vertical-tab characters in the output 
stream are collectively known as embedded carriage control.) 


SMBMSG$K_CHARACTERISTICS 

This code identifies a 16-byte structure specifying characteristics of the job. A 
detailed description of the format of this structure is contained in the description 
of the QUI$ CHARACTERISTICS code in the $GETQUI system service in the 
HP OpenVMS System Services Reference Manual. 


SMBMSG$K_DEVICE_NAME 

This code identifies a string that is the name of the device to which the symbiont 
is to send data. The symbiont interprets this information. The name need not 
be the name of a physical device, and the symbiont can interpret this string as 
something other than the name of a device. 


SMBMSG$K_ENTRY_NUMBER 
This code identifies a longword containing the number that the job controller 
assigned to the job. 


SMBMSG$K_EXECUTOR_QUEUE 
This code identifies a string that is the name of the queue on which the symbiont 
stream is to be started. 


SMBMSG$K_FILE_COPIES 
This code identifies a longword containing the number of copies of the file that 
were requested. 


SMBMSG$K_FILE_COUNT 

This code identifies a longword that specifies, out of the number of copies 
requested for this job (GMBMSG$K_FILE COPIES), the number of the copy of 
the file currently printing. 


SMBMSG$K_FILE_IDENTIFICATION 

This code identifies a 28-byte structure identifying the file to be processed. This 
structure consists of the following three file-identification fields in the OpenVMS 
RMS NAM block: 


1. The 16-byte NAM$T_DVI field 
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2. The 6-byte NAM$W FID field 
3. The 6-byte NAM$W _DID field 


These fields occur consecutively in the NAM block in the order listed. 


SMBMSG$K_FILE_SETUP_MODULES 

This code identifies a string specifying the names (separated by commas) of one or 
more text modules that the symbiont should copy from the library into the output 
stream before processing the file. 


SMBMSG$K_FILE_SPECIFICATION 
This code identifies a string specifying the name of the file that the symbiont is to 
process. This file name is formatted as a standard RMS file specification. 


SMBMSG$K_FIRST_PAGE 

This code identifies a longword containing the number of the page at which 
the symbiont should begin printing. The job controller sends this item to the 
symbiont. When not specified, the symbiont begins processing at page 1. 


SMBMSG$K_FORM_LENGTH 
This code identifies a longword value specifying the length (in lines) of the 
physical form (the paper). 


SMBMSG$K_FORM_NAME 
This code identifies a string specifying the name of the form. 


SMBMSG$K_FORM_SETUP_MODULES 

This code identifies a string consisting of the names (separated by commas) of one 
or more modules that the symbiont should copy from the device-control library 
before processing the file. 


SMBMSG$K_FORM_WIDTH 
This code identifies a longword specifying the width (in characters) of the print 
area on the physical form (the paper). 


SMBMSG$K_JOB_COPIES 
This code identifies a longword specifying the requested number of copies of the 
job. 


SMBMSG$K_JOB_COUNT 

This code identifies a longword specifying, out of the number of copies requested 
(SMBMSG$K_J OB COPIES), the number of the copy of the job currently 
printing. 


SMBMSG$K_JOB_NAME 
This code identifies a string specifying the name of the job. 


SMBMSG$K_JOB_RESET_MODULES 

This code identifies a string specifying a list of one or more module names 
(Separated by commas) that the symbiont should copy from the device 
control library after processing the task. These modules can be used to reset 
programmable devices to a known state. 
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SMBMSG$K_LAST_PAGE 

This code identifies a longword specifying the number of the last page that the 
symbiont is to print. When not specified, the symbiont attempts to print all the 
pages in the file. 


SMBMSG$K_LEFT_MARGIN 
This code identifies a longword specifying the number of spaces to be inserted at 
the beginning of each line. 


SMBMSG$K_LIBRARY_SPECIFICATION 
This code identifies a string specifying the name of the device-control library. 


SMBMSG$K_MESSAGE_VECTOR 
This code identifies a vector of longword condition codes, each of which contains 
information about the job to be printed. 


When LOGINOUT cannot open a log file for a batch job, a code in the message 
vector specifies the reason for the failure. The job controller does not send the 
SMBMSG$K_FILE_IDENTIFICATION item if it has detected such a failure 
but instead sends the message vector, which the symbiont prints, along with a 
message stating that there is no file to print. 


SMBMSG$K_NOTE 
This code identifies a user-supplied string that the symbiont is to print on the job 
flag page and on the file flag page. 


SMBMSG$K_PAGE_SETUP_MODULES 

This code identifies a string consisting of the names (Separated by commas) of one 
or more modules that the symbiont should copy from the device-control library 
before printing each page. 


SMBMSG$K_PARAMETER_1 through SMBMSG$K_PARAMETER_8 

Each of these eight codes identifies a user-supplied string. Both the semantics 
and syntax of each string are determined by the user-defined symbiont. The 
OpenVM S-supplied symbiont makes no use of these eight items. 


SMBMSG$K_PRINT_CONTROL 
This code identifies a longword bit vector, each bit of which supplies information 
that the symbiont is to use in controlling the printing of the file. 


Symbol Description 

SMBMSG$V_DOUBLE_SPACE The symbiont uses a double-spaced 
format; it skips a line after each line 
it prints. 

SMBMSG$V_NO_INITIAL_FF The symbiont suppresses the initial 


form feed if this bit is turned on. 


SMBMSG$V_NORECORD BLOCKING The symbiont performs single record 
output, issuing a single output record 
for each input record. 

SMBMSG$V_PAGE_ HEADER The symbiont prints a page header 
at the top of each page. 
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Symbol 


Description 


SMBMSG$V_PAGINATE 


SMBMSG$V_PASSALL 


SMBMSG$V_RECORD_BLOCKING 


SMBMSG$V_SEQUENCED 
SMBMSG$V_SHEET_FEED 


SMBMSG$V_TRUNCATE 


SMBMSG$V_WRAP 


The symbiont inserts a form feed 
character when it detects an attempt 
to print in the bottom margin of the 
current form. 


The symbiont prints the file 

without formatting and bypasses 

all formatting normally performed. 
Furthermore, the symbiont outputs 
the file without formatting, by 
causing the output QIO to suppress 
formatting by the driver. 

The symbiont performs record 
blocking, buffering output to the 
device. 

This bit is reserved by HP. 

The symbiont pauses the queue after 
each page it prints. 

The symbiont truncates input lines 
that exceed the right margin of the 
current form. 

The symbiont wraps input lines that 
exceed the right margin, printing the 
additional characters on a new line. 


SMBMSG$K_PRIORITY 


This code identifies a longword specifying the priority this job has in the queue in 


which it is entered. 


SMBMSG$K_QUEUE 


This code identifies a string specifying the name of the queue in which this job 
is entered. When generic queues are used, this item specifies the name of the 
generic queue, and the SMBMSG$K_EXECUTOR item specifies the name of the 


device queue or the server queue. 


SMBMSG$K_RELATIVE_PAGE 


This code identifies a signed, longword value specifying the number of pages that 
the symbiont is to move forward (positive value) or backward (negative value) 


from the current position in the file. 


SMBMSG$K_REQUEST_CONTROL 


This code identifies a longword bit vector, each bit of which specifies information 
that the symbiont is to use in processing the request that the job controller is 


making. 


Symbiont/Job Controller Interface (SMB) Routines SMB-27 


Symbiont/Job Controller Interface (SMB) Routines 
SMB$READ_MESSAGE_ITEM 


Symbol Description 


SMBMSG$V_ALIGNMENT_MASK The symbiont is to replace all 
alphabetic characters with the letter 
X, and all numeric characters with 
the number 9. Other characters 
(punctuation, carriage control, 
and so on) are left unchanged. 
This bit is ordinarily specified in 
connection with the SMBMSG$K _ 
ALIGNMENT_PAGES item. 


SMBMSG$V_PAUSE_COMPLETE The symbiont is to pause when it 
completes the current request. 
SMBMSG$V_RESTARTING Indicates that this job was previously 


interrupted and requeued, and is 
now restarting. 

SMBMSG$V_TOP_OF_FILE The symbiont is to rewind the input 
file before it resumes printing. 


SMBMSG$K_RIGHT_MARGIN 

This code identifies a longword specifying the number of character positions to 
be left empty at the end of each line. When the right margin is exceeded, the 
symbiont truncates the line, wraps the line, or continues processing, depending 
on the settings of the WRAP and TRUNCATE bits in the SMBMSG$K_PRINT_ 
CONTROL item. 


SMBMSG$K_SEARCH_STRING 

This code identifies a string containing the value specified in the 
START/QUEUE/SEARCH command. This string identifies the page at which 
to restart the current printing task on a paused queue. 


SMBMSG$K_SEPARATION_CONTROL 

This code identifies a longword bit vector, each bit of which specifies an operation 
that the symbiont is to perform between jobs or between files within a job. The 
$SMBDEF macro defines the following symbols for each bit: 


Symbol Description 

SMBMSG$V_FILE_BURST The symbiont is to print a file burst 
page. 

SMBMSG$V_FILE_FLAG The symbiont is to print a file flag 
page. 

SMBMSG$V_FILE_TRAILER The symbiont is to print a file trailer 
page. 


SMBMSG$V_FILE_TRAILER_ABORT The symbiont is to print a file 
trailer page when a task completes 
abnormally. 

SMBMSG$V_FIRST_FILE_OF_J OB The current file is the first file 
of the job. When specified with 
SMBMSG$V_LAST_FILE_OF_J OB, 
the current job contains a single file. 
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Symbol Description 

SMBMSG$V_J OB FLAG The symbiont is to print a job flag 
page. 

SMBMSG$V_J OB_ BURST The symbiont is to print a job burst 
page. 

SMBMSG$V_J OB_RESET The symbiont is to execute a job reset 
sequence when the task completes. 

SMBMSG$V_J OB_RESET_ABORT The symbiont is to execute a job reset 
sequence when a task completes 
abnormally. 

SMBMSG$V_JOB_ TRAILER The symbiont is to print a job trailer 
page. 

SMBMSG$V_J OB_TRAILER_ABORT The symbiont is to print a job 
trailer page when a task completes 
abnormally. 

SMBMSG$V_LAST_FILE_OF_J OB The current file is the last file 


of the job. When specified with 
SMBMSG$V_FIRST_FILE_OF_J OB, 
the current job contains a single job. 


SMBMSG$K_STOP_CONDITION 
This code identifies a longword containing a condition specifying the reason the 
job controller issued a STOP_TASK request. 


SMBMSG$K_TIME_QUEUED 
This code identifies a quadword specifying the time the file was entered into the 
queue. The time is expressed as 64-bit, absolute time. 


SMBMSG$K_TOP_MARGIN 

This code identifies a longword specifying the number of lines that the symbiont 
is to leave blank at the top of each page. PRTSMB inserts line feeds into the 
output stream after every form feed until the margin is cleared. 


SMBMSG$K_UIC 
This code identifies a longword specifying the user identification code (UIC) of the 
user who submitted the job. 


SMBMSG$K_USER_NAME 
This code identifies a string specifying the name of the user who submitted the 
job. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
SMB$ NOMOREITEMS End of item list reached. 


This routine also returns any condition code returned by the Run-Time Library 
string-handling (STR$) routines. 
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SMB$SEND_TO JOBCTL—Send Message to Job Controller 


The SMB$SEND_TO_J OBCTL routine is used by your symbiont to send messages 
to the job controller. Three types of messages can be sent: request-completion 
messages, task-completion messages, and task-status messages. 


Format 
SMB$SEND_TO_JOBCTL stream [,request] [,accounting] [,checkpoint] 
[,device_status] [,error] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
stream 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Stream number specifying the stream to which the message refers. The stream 
argument is the address of a longword containing the number of the stream to 
which the message refers. 


request 

OpenVMS usage: identifier 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Request code identifying the request being completed. The request argument is 
the address of a longword containing the code that identifies the request that has 
been completed. 


The code usually corresponds to the code the job controller passed to the symbiont 
by means of a call to SMB$READ_ MESSAGE. But the symbiont can also initiate 
task-completion and task-status messages that are not in response to a request. 
(See the Description section.) 
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accounting 

OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Accounting information about a task. The accounting argument is the address 
of a descriptor pointing to the accounting information about a task. Note that 
this structure is passed by descriptor and not by reference. 


The job controller accumulates task statistics into a job-accounting record, which 
it writes to the accounting file when the job is completed. 


The following diagram depicts the contents of the 16-byte structure: 


31 0 


ZK-2012-GE 
checkpoint 
OpenVMS usage: char_string 
type: character string 
access: read only 
mechanism: by descriptor 


Checkpoint data about the currently executing task. The checkpoint argument 
is the address of the descriptor that points to checkpointing information that 
relates to the status of a task. When the symbiont sends this information to 

the job controller, the job controller saves it in the queue database. When a 
restart-from-checkpoint request is executed for the queue, the job controller 
retrieves the checkpointing information from the queue database and sends it to 
the symbiont in the SMBMSG$K_CHECKPOINT_DATA item that accompanies a 
SMBMSG$K_START_TASK request. 


Print symbionts can use the checkpointing information to reposition the input 
file to the point corresponding to the page being output when the last checkpoint 
was taken. Other symbionts might use checkpoint information to specify restart 
information for partially completed tasks. 


Note 


Because each checkpoint causes information to be written into the 

job controller’s queue database, taking a checkpoint incurs significant 
overhead. Use caution in regard to the size and frequency of checkpoints. 
When determining how often to checkpoint, weigh processor and file 
system overhead against the convenience of restarting. 
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device_status 
OpenVMS usage: longword_unsigned 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Status of the device served by the symbiont. The device_status argument is the 
address of a longword passed to the job controller, which contains the status of 
the device to which the symbiont is connected. 


This longword contains a longword bit vector, each bit of which specifies device- 
status information. Each programming language provides an appropriate 
mechanism for defining these device-status bits. The following table describes 


each bit: 

Device Status Bit Description 

SMBMSG$V_LOWERCASE The device to which the symbiont is connected 
supports lowercase characters. 

SMBMSG$V_PAUSE_TASK The symbiont sends this message to inform 
the job controller that the symbiont has 
paused on its own initiative. 

SMBMSG$V_REMOTE The device is connected to the symbiont by 
means of a modem. 

SMBMSG$V_SERVER The symbiont is not connected to a device. 

SMBMSG$V_STALLED Symbiont processing is temporarily stalled. 


SMBMSG$V_STOP_STREAM The symbiont requests that the job controller 
stop the queue. 
SMBMSG$V_TERMINAL The symbiont is connected to a terminal. 


SMBMSG$V_UNAVAILABLE The device to which the symbiont is connected 
is not available. 


error 
OpenVMS usage: vector_longword_unsigned 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Condition codes returned by the requested task. The error argument is the 
address of a vector of longword condition codes. The first longword contains the 
number of longwords following it. 


If the low bit of the first condition code is clear, the job controller aborts 
further processing of the job. Output of any remaining files, copies of files, or 
copies of the job is canceled. In addition, the job controller saves up to three 
condition values in the queue database. The first condition value is included 
in the job-accounting record that is written to the system's accounting file 
(SY S$MANAGER:ACCOUNTNG.DAT). 


SMB-32 Symbiont/Job Controller Interface (SMB) Routines 


Description 


Symbiont/Job Controller Interface (SMB) Routines 
SMB$SEND_TO_JOBCTL 


The symbiont uses the SMB$SEND_TO_J OBCTL routine to send messages to the 
job controller. 


Most messages the symbiont sends to the job controller are responses to requests 
made by the job controller. These responses inform the job controller that the 
request has been completed, either successfully or with an error. When the 
symbiont sends the message, it usually indicates that the request has been 
completed. 


In such messages, the request argument corresponds to the function code of 
the request that has been completed. Thus, if the job controller sends a request 
using the SMBMSG$K_START_TASK code, the symbiont responds by sending 
a SMB$SEND_TO_J OBCTL message using SMBMSG$K_START_TASK as the 
request argument. 


The responses to some requests use additional arguments to send more 
information in addition to the request code. The following table shows which 
additional arguments are allowed in response to each different request: 


Request Arguments 
SMBMSG$K_START_ STREAM request 
device_status 
error 
SMBMSG$K_STOP_STREAM request 
SMBMSG$K_RESET STREAM request 
SMBMSG$K_START_TASK request 
SMBMSG$K_PAUSE_TASK request 
SMBMSG$K_RESUME_TASK request 
SMBMSG$K_STOP_TASK request 
error! 


1This is usually the value specified in the SMBMSG$K_STOP_CONDITION item that was sent by the 
job controller with the SMBMSG$K_STOP_TASK request. 


In addition to responding to requests from the job controller, the symbiont can 
send other messages to the job controller. If the symbiont sends a message that is 
not a response to a request, it uses either the SMBMSG$K_TASK_COMPLETE or 
SMBMSG$K_TASK_STATUS code. Following are the additional arguments that 
you can use with the messages identified by these codes: 


Code Arguments 

SMBMSG$K_TASK_ COMPLETE request 
accounting 
error 

SMBMSG$K_TASK_STATUS request 
checkpoint 


device_status 
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The symbiont uses the SMBMSG$K_TASK_ STATUS message to update the 
job controller on the status of a task during the processing of that task. The 
checkpoint information passed to the job controller with this message permits 
the job controller to restart an interrupted task from an appropriate point. The 
device-status information permits the symbiont to report changes in device's 
status (device stalled, for example). 


The symbiont can use the SMBMSG$K_TASK_ STATUS message to request 
that the job controller send a stop-stream request. It does this by setting the 
stop-stream bit in the device-status argument. 


The symbiont can also use the SMBMSG$K_TASK STATUS message to notify 
the job controller that the symbiont has paused in processing a task. It does so 
by setting the pause-task bit in the device-status argument. 


The symbiont uses the SMBMSG$K_TASK COMPLETE message to signal the 
completion of a task. Note that, when the symbiont receives a START_TASK 
request, it responds by sending a SMB$SEND_TO J OBCTL message with 
SMBSMG$K_START_TASK as the request argument. This response means that 
the symbiont has started the task; it does not mean the task has been completed. 
When the symbiont has completed a task, it sends a SMB$SEND_TO_ J OBCTL 
message with SMBMSG$K_TASK COMPLETE as the request argument. 


Optionally, the symbiont can specify accounting information when sending a 
task-completion message. The accounting statistics accumulate to give a total for 
the job when the job is completed. 


Also, if the symbiont is aborting the task because of a symbiont-detected error, 
you can specify up to three condition values in the error argument. Aborting a 
task causes the remainder of the job to be aborted. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 


This routine also returns any condition value returned by the $QIO system 
service and the LIB$GET_VM routine. 
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Sort/Merge (SOR) Routines 


The Sort/Merge (SOR) routines allow you to integrate a sort or merge operation 
into a program application. Using these callable routines, you can process 
records, sort or merge them, and then process them again. 


20.1 High-Performance Sort/Merge (Alpha Only) 


You can also choose the high-performance Sort/Merge utility. This utility takes 
advantage of the Alpha architecture to provide better performance for most sort 
and merge operations. 


In addition, the high-performance Sort/Merge utility can increase performance 
by using threads to take advantage of multiple processors on an SMP configured 
system. Refer to Section 20.1.2 for further information about using threads. 


The high-performance Sort/Merge utility supports a subset of the SOR routines. 
Any differences between the high-performance Sort/Merge utility and Sort/Merge 
utility (GORT/MERGE) are noted within this chapter. 


Note 


Memory allocation differences may limit the high-performance Sort/M erge 
utility’s ability to perform the same number of concurrent sort operations 
as the Sort/Merge utility can perform in the same amount of virtual 
memory. 


If this situation occurs, you can either increase the amount of virtual 
memory that is available to the process, or reduce the working set extent. 
For information on using system parameters to change the amount of 
virtual memory or reduce the working set extent, refer to the OpenVMS 
Systen Management Utilities Reference Manual. 


Use the SORTSHR logical name to select the high-performance Sort/Merge 
utility. Define SORTSHR to point to the high-performance sort executable in 
SYS$LIBRARY as follows: 


$ define sortshr sys$library:hypersort.exe 


To return to SORT/MERGE, deassign SORTSHR. The Sort/Merge utility is the 
default if SORTSHR is not defined. 
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20.1.1 High-Performance SOR Routine Behavior 


The behavior of the SOR routines for the high-performance Sort/Merge utility is 
the same as for SORT/MERGE except as shown in Table 20-1. 


If you attempt to use an unsupported capability, the high-performance Sort/M erge 
utility generates an error. The high-performance Sort/Merge utility adds the 
following condition value to those listed for SORT/MERGE: 


SOR$_ NYI Attempt to use a feature that is not yet implemented. 


Table 20-1 High-Performance Sort/Merge: Differences in SOR$ Routine 


Behavior 
Feature High-Performance Sort/Merge Behavior 
Work files Permissible values of the SOR$BEGIN_SORT work_ 
files argument range from 1 through 255. By default, 
the high-performance Sort/Merge utility creates two 
temporary work files. 
Input file size If you do not specify an input file size in the 


Specification files 


Key data types 


Key data types not normally 


supported by SORT/MERGE 


Internal sorting processes 
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SOR$BEGIN_SORT file_alloc argument, the high- 
performance Sort/Merge utility determines a default 
based on the size of the input file, or if input is not 
from files, on available memory. 


The SOR$SPEC FILE routine is not supported. 
(Implementation of this feature is deferred to a future 
OpenVMS Alpha release.) 


DSC$K_DTYPE_O, DSC$K_DTYPE_OU, DSC$K_ 
DTYPE_H, and DSC$K_DTYPE_NZ are not valid 

key data types in the SOR$BEGIN_MERGE 

or SOR$BEGIN_SORT key_buffer argument. 
(Implementation of this feature is deferred to a future 
OpenVMS Alpha release.) 


The SOR$DTYPE routine is not supported. 
(Implementation of this feature is deferred to a future 
OpenVMS Alpha release.) Data types that would 
otherwise be specified using SOR$DTYPE indude 
extended data types and the National Character Set 
(NCS) collating sequences. 


Only the record sort process is supported. You 

can specify the SOR$BEGIN_SORT routine sort_ 
process argument as SOR$GK_RECORD or omit the 
argument. The SOR$GK_TAG, SOR$GK_ADDRESS, 
and SOR$GK_INDEX values are not supported for 
the sort_process argument. (Implementation of 
this feature is deferred to a future OpenVMS Alpha 
release.) 


(continued on next page) 
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Table 20-1 (Cont.) High-Performance Sort/Merge: Differences in SOR$ Routine 
Behavior 


Feature High-Performance Sort/Merge Behavior 


Statistical summary information The following statistics are currently supported: 


Records read/input (SOR$K_REC_INP) 
Records sorted (SOR$K_REC_SOR) 
Records output (SOR$K_REC_OUT) 
Input record length (SOR$K_LRL_INP) 


The following statistics are currently unavailable: 


Internal length 

Output record length 
Sort tree size 

Number of initial runs 
Maximum merge order 
Number of merge passes 
Work file allocation 


Full implementation of this feature is deferred toa 
future OpenVMS Alpha release. 


User-supplied action routines The following user-supplied action routines are 
not supported for either SOR$BEGIN_MERGE or 
SOR$BEGIN_SORT. (Implementation of this feature 
is deferred to a future OpenVMS Alpha release.) You 
must provide a placeholder comma (,) in the argument 
list if other arguments follow the customary position of 
the user_compare or user_equal argument. 


user_compare Compares records to determine 
their sort or merge order. 


user_equal Resolves the sort or merge order 
when records have duplicate keys. 


20.1.2 Using Threads with High-Performance Sort/Merge 


The high-performance Sort/Merge utility can take advantage of multiple 
processors on an SMP configured system by using threads to gain additional 
performance. Threads use is optimized under the following conditions: 


e theSYSGEN parameter MULTITHREAD is set to the number of CPUs on 
the system 


e the base image of the application using the high-performance Sort/Merge 
utility is linked with the /THREADS ENABLE qualifier 


When linking an executable image that uses the high-performance Sort/Merge 
utility, the executable should be linked with the /THREADS_ENABLE linker 
qualifier. Either /THREADS ENABLE or /THREADS ENABLESMULTIPLE_ 
KERNEL_THREADS,UPCALLS) qualifiers may be used. (Refer to the Guide to 
DECthreads manual in the OpenVMS documentation set for more information on 
this linker qualifier.) 


The high-performance Sort/Merge utility will not utilize multiple processors, 
and therefore won’t run at peak performance, if the /THREADS ENABLE linker 
qualifier is omitted, explicitly disabled (by the /(NOTHREADS ENABLED), 

or partially enabled (by the /THREADS_ENABLE=UPCALLS or /THREADS_ 
ENABLE=MULTIPLE_KERNEL_THREADS). However, the high-performance 
Sort/Merge utility will still run and produce correct results. 
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20.2 Introduction to SOR Routines 


The following SOR routines are available for use in a sort or merge operation: 


Routine 


Description 


SOR$BEGIN_MERGE 
SOR$BEGIN_SORT 


SOR$DTY PE 


SOR$END_SORT 
SOR$PASS FILES 
SOR$RELEASE_REC 
SOR$RETURN_REC 


SOR$SORT_MERGE 
SOR$SPEC FILE 


Sets up key arguments and performs the merge. This is the 
only routine unique to MERGE. 


Initializes the sort operation by passing key information and 
sort options. This is the only routine unique to SORT. 


Defines a key data-type that is not normally supported by 
SORT/MERGE. (This feature is not currently supported by 
the high-performance Sort/M erge utility.) 


Performs cleanup functions, such as closing files and 
releasing memory. 


Passes names of input and output files to SORT or MERGE; 
must be repeated for each input file. 


Passes one input record to SORT or MERGE; must be called 
once for each record. 


Returns one sorted or merged record to a program; must be 
called once for each record. 


Sorts the records. 
Passes a specification file or specification text. A call 


to this routine must precede all other calls to the SOR 
routines. (This feature is not currently supported by the 
high-performance Sort/M erge utility.) 


SOR$STAT Returns a statistic about the sort or merge operation. (This 
feature is partially supported by the high-performance 


Sort/M erge utility.) 


You can call these SOR routines from any language that supports the OpenVMS 
calling standard. Note that the application program should declare referenced 
constants and return status symbols as external symbols; these symbols will be 
resolved upon linking with the utility shareable image. 


After being called, each of these routines performs its function and returns control 
to a program. It also returns a 32-bit condition code value indicating success or 
error, which a program can test to determine success or failure conditions. 


20.2.1 Arguments to SOR Routines 


For a sort operation, the arguments to the SOR routines provide SORT with file 
specifications, key information, and instructions about the sorting process. For a 
merge operation, the arguments to the SOR routines provide MERGE with the 
number of input files, input and output file specifications, record information, 
key information, and input routine information. To perform sort or merge 
operations, you must pass key information (key_buffer argument) to either 

the SOR$BEGIN_SORT or SOR$BEGIN_MERGE routine. The key_buffer 
argument is passed as an array of words. The first word of the array contains the 
number of keys to be used in the sort or merge. Each block of four words that 
follows describes one key (multiple keys are listed in order of their priority): 


e The first word of each block describes the key data type. 


e The second word determines the sort or merge order (0 for ascending, 1 for 
descending). 
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e« The third word describes the relative offset of the key (beginning at position 
0). 


e The fourth word describes the length of the key in bytes. 


There are both mandatory and optional arguments. The mandatory arguments 
appear first in the argument list. You must specify all arguments in the order in 
which they are positioned in the argument list, separating each with a comma. 
Pass a zero by value to specify any optional arguments that you are omitting 
from within the list. You can end the argument list any time after specifying all 
the mandatory and desired optional arguments. 


20.2.2 Interfaces to SOR Routines 


You can submit data to the SOR routines as complete files or as single records. 
When your program submits one or more files to SORT or MERGE, which then 
creates one sorted or merged output file, you are using the file interface. When 
your program submits records one at a time and then receives the ordered records 
one at a time, you are using the record interface. 


You can combine the file interface with the record interface by submitting files 
on input and receiving the ordered records on output or by releasing records on 
input and writing the ordered records to a file on output. Combining the two 
interfaces provides greater flexibility. If you use the record interface on input, 
you can process the records before they are sorted; if you use the record interface 
on output, you can process the records after they are sorted. 


The SOR routines used and the order in which they are called depend on the type 
of interface used in a sorting or merging operation. The following sections detail 
the calling sequence for each of the interfaces. 


20.2.2.1 Sort Operation Using File Interface 
For a sort operation using the file interface, pass the input and output file 
specifications to SORT by calling SOR$PASS FILES. You must call SOR$PASS — 
FILES for each input file specification. Pass the output file specification in the 
first call. If no input files are specified before the call to SOR$BEGIN_ SORT, the 
record interface is used for input; if no output file is specified, the record interface 
is used for output. 


Next, call SOR$BEGIN_ SORT to pass instructions about keys and sort options. 
At this point, you must indicate whether you want to use your own key 
comparison routine. (This feature is not currently supported by the high- 
performance Sort/Merge utility.) SORT automatically generates a key comparison 
routine that is efficient for key data types; however, you might want to provide 
your own comparison routine to handle special sorting requirements. (For 
example, you might want names beginning with “Mc” and “Mac” to be placed 
together.) If you use your own key comparison routine, you must pass its address 
with the user_compare argument. 


Call SOR$¢SORT_MERGE to execute the sort and direct the sorted records to the 
output file. Finally, call SORSEND_ SORT to end the sort and release resources. 
The SOR$END_SORT routine can be called at any time to abort a sort or to 
merge and release all resources allocated to the sort or merge process. 


Sort/Merge (SOR) Routines SOR-5 


Sort/Merge (SOR) Routines 
20.2 Introduction to SOR Routines 


20.2.2.2 Sort Operation Using Record Interface 
For a sort operation using the record interface, first call SOR$BEGIN_SORT. As 
in the file interface, this routine sets up work areas and passes arguments that 
define keys and sort options. Note that, if you use the record interface, you must 
use a record-sorting process (not a tag, address, or index process). 


Next, call SOR$RELEASE REC to release a record to SORT. Call 
SOR$RELEASE_REC once for each record to be released. After all records 
have been passed to SORT, call SOR$SORT_MERGE to perform the sorting. 


After the sort has been performed, call SOR$RETURN_REC to return a record 
from the sort operation. Call this routine once for each record to be returned. 
Finally, call the last routine, SOR$¢END_SORT, to complete the sort operation 
and release resources. 


20.2.2.3 Merge Operation Using File Interface 
For a merge operation using the file interface, pass the input and output file 
specifications to MERGE by calling SOR$PASS FILES. You can merge up to 
10 input files. (The high-performance Sort/Merge utility allows you to merge 
up to 12 input files.) by calling SOR$PASS FILES once for each file. Pass the 
file specification for the merged output file in the first call. If no input files are 
specified before the call to SOR$BEGIN_ MERGE, the record interface is used for 
input; if no output file is specified, the record interface is used for output. 


Next, to execute the merge, call SOR$BEGIN_ MERGE to pass key information 
and merge options. At this point, you must indicate whether you want to use your 
own key comparison routine tailored to your data. (This feature is not currently 
supported by the high-performance Sort/Merge utility.) Finally, call SORSEND_ 
SORT to release resources. 


20.2.2.4 Merge Operation Using Record Interface 
For a merge operation using the record interface, first call SOR$¢BEGIN_ MERGE. 
As in the file interface, this routine passes arguments that define keys and merge 
options. It also issues the first call to the input routine, which you must create, 
to begin releasing records to the merge. 


Next, call SOR$¢RETURN_REC to return the merged records to your program. 
You must call this routine once for each record to be returned. SOR$RETURN_ 
REC continues to call the input routine. MERGE, unlike SORT, does not need 
to hold all the records before it can begin returning them in the desired order. 
Releasing, merging, and returning records all take place in this phase of the 
merge. 


Finally, after all the records have been returned, call the last routine, SOR$END_ 
SORT, to clean up and release resources. 


20.2.3 Reentrancy 


The SOR routines are reentrant; that is, a number of sort or merge operations 
can be active at the same time. Thus, a program does not need to finish one sort 
or merge operation before beginning another. For example, reentrancy lets you 
perform multiple sorts on a file such as a mailing list and to create several output 
files, one with the records sorted by name, another sorted by state, another sorted 
by zip code, and so on. 
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The context argument, which can optionally be passed with any of the SOR 
routines, distinguishes among multiple sort or merge operations. When using 
multiple sort or merge operations, the context argument is required. On the 
first call, the context longword must be zero. It is then set (by SORT/MERGE) to 
a value identifying the sort or merge operation. Additional calls to the same sort 
or merge operation must pass the same context longword. The SOR$END_ SORT 
routine clears the context longword. 
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20.3 Using the SOR Routines: Examples 


This section provides examples of using the SOR routines for various operations 
including the following: 


Example 20-1 is a HP Fortran program that demonstrates a merge operation 
using a record interface. 


Example 20-2 is a HP Fortran program that demonstrates a sort operation 
using a file interface on input and a record interface on output. 


Example 20-3 is a HP Pascal program that demonstrates a merge operation 
using a file interface. 


Example 20-4 is a HP Pascal program that demonstrates a sort operation 
using a record interface. 


Example 20-5 is a HP C program that demonstrates a sort operation using 
the STABLE option and two text keys. 
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Example 20-1 Using SOR Routines to Perform a Merge Using Record Interface in a HP 
Fortran Program 


Fortran Program 
This program demonstrates the Fortran calling sequences 
for the merge record interface. 
THE INPUT FILES ARE LISTED BELOW. 
INFILE1.DAT 


1 BBBBBBBBBB REST OF DATA IN RECORD: 64 csc4 ca e5 se oa gerage es Sree ees es END OF RECORD 
2 UUUUUUUUUU REST OF DATA IN RECORD... 1... cee ccc eee eee END OF RECORD 


INFILE2 . DAT 


1 AAAAAAAAAA REST OF DATA IN RECORD. 1... ccc ccc ce ee eee ee eee END OF RECORD 
2 PETTITTE REST. OF DATA: IN -RECORD J...) cisiiesi gia eiieie di 84 FS Ge HAAS ALG SG DAISIES END OF RECORD 


INFILE3 . DAT 


I TTETIIEIEE REST. OF DATA EN RECORD 0.4 cies choy Soa age eS Gals ee END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD.......... cece cece ee eee eee END OF RECORD 
FOROUT . DAT 
1 AAAAAAAAAA REST OF DATA IN RECORD... 1... ccc cee ce ee eee END OF RECORD 
1 BBBBBBBBBB REST OF DATA IN RECORD. ....... ccc cee ee eee eee END OF RECORD 
1, TEITTITITI REST: OF (DATA: IN) -RECORD siete onsets Mieiwten a aaa ea ad aa ae gia was END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD........ ccc cece eee e secre en seeees END OF RECORD 
2 TTITTTTTTTT REST OF DATA IN RECORD......... ccc cece ee eee END OF RECORD 
2 UUUUUUUUUU REST OF DATA IN RECORD........ ccc ec ee eee ees END OF RECORD 


AAAAAAAAARA ARMA RAAAAAARAAAAAAAAAAAAA 


AA 


IMPLICIT INTEGER (A-Z) 


CHARACTER* 80 REC ! A record. 

EXTERNAL READ REC ! Routine to read a record. 
EXTERNAL KOMPAR ! Routine to compare records. 
EXTERNAL SS$ ENDOFFILE ! System end-of-file value 
INTEGER*4 SORSBEGIN MERGE ! SORT/MERGE function names 


INTEGER*4 SORSRETURN REC 
INTEGER*4 SORSEND SORT 


INTEGER*4 ISTAT ! storage for SORT/MERGE function value 
INTEGER*4 LENGTH ! length of the returned record 
INTEGER*2 LRL ! Longest Record Length (LRL) 

LOGICAL*1 ORDER ! #files to merge (merge order) 

DATA ORDER, LRL/3,80/ ! Order of the merge=3,LRL=80 


(continued on next page) 
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Example 20-1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a 
HP Fortran Program 


First open all the input files. 


aa 


OPEN (UNIT=10, FILE=’INFILE1.DAT’ , TYPE='OLD’ , READONLY, 
* FORM=' FORMATTED’ 
OPEN (UNIT=11, FILE=’INFILE2.DAT’ , TYPE='OLD’ , READONLY, 
* FORM=' FORMATTED’ 
OPEN (UNIT=12, FILE='INFILE3.DAT’ , TYPE='OLD‘ , READONLY, 
* FORM=' FORMATTED’ 


Open the output file. 


ome e @) 


OPEN (UNIT=8, FILE='TEMP.TMP’, TYPE='NEW’) 


Initialize the merge. Pass the merge order, the largest 
record length, the compare routine address, and the 
input routine address. 


AAARARA 


ISTAT = SORSBEGIN MERGE (, LRL, , ORDER, 
* KOMPAR, , READ REC) 
IF (.NOT. ISTAT) GOTO 10 ! Check for error. 


Now loop getting merged records. SORSRETURN REC will 
call READ REC when it needs input. 


WAAARARAA 


ISTAT = SORSRETURN_REC (REC, LENGTH) 
IF (ISTAT .EQ. LOC (SS$_ENDOFFILE) ) GO TO 30 ! Check for end of file. 
IF (.NOT. ISTAT) GO TO 10 ! Check for error. 


WRITE(8,200) REC ! Output the record. 
200 FORMAT(’ ‘,A 
GOTO 5 ! And loop back. 


Cy 

Cua Now tell SORT that we are all done. 
C 

3 


0 ISTAT = SORSEND_ SORT () 
IF (.NOT. ISTAT) GOTO 10 ! Check for error. 
CALL EXIT 


Cte 
Cras Here if an error occurred. Write out the error status 
Cc and exit. 


10 WRITE (8,201) ISTAT 

201 FORMAT(' ?ERROR CODE’, 120) 
CALL EXIT 
END 


FUNCTION READ REC (RECX, FILE, SIZE) 


This routine reads a record from one of the input files 
for merging. It will be called by SORSBEGIN MERGE and by 
SORSRETURN_REC. 

Parameters: 


RECX.wcp.ds character buffer to hold the record after 
it is read in. 


OO AAA AAA 
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Example 20-1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a 
HP Fortran Program 


Cis FILE.rl.r indicates which file the record is 

Cieaz to be read from. 1 specifies the 

Co first file, 2 specifies the second 

Cas etc. 

Cs 

Ce. LENGTH.wl.r is the actual number of bytes in 

Cie the record. This is set by READ REC. 

Cio 
IMPLICIT INTEGER (A-Z) 
PARAMETER MAXFIL=10 ! Max number of files. 
EXTERNAL SS$_ENDOFFILE ! End of file status code. 
EXTERNAL SS$_NORMAL ! Success status code. 
LOGICAL*1 FILTAB (MAXFIL) 
CHARACTER* (80) RECX ! MAX LRL =80 
DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ ! Table of I/O unit numbers. 
READ REC = %LOC(SS$_ENDOFFILE) ! Give end of file return 
IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN ! if illegal call. 
READ (FILTAB(FILE), 100, ERR=75, END=50) RECX ! Read the record. 

100 FORMAT (A) 
READ REC = %LOC(SS$ NORMAL) ! Return success code. 
SIZE = LEN (RECX) ! Return size of record. 
RETURN 

Chas Here if end of file. 

50 READ REC = %LOC(SS$_ENDOFFILE) ! Return "end of file" code. 
RETURN 

Ces Here if error while reading 

75 READ REC = 0 
SIZE = 0 
RETURN 
END 
FUNCTION KOMPAR (REC1,REC2) 

Ci 

Cas This routine compares two records. It returns -1 

Ces if the first record is smaller than the second, 

Cia 0 if the records are equal, and 1 if the first record 

Ca% is larger than the second. 

Cus 


PARAMETER KEYSIZ=10 
IMPLICIT INTEGER (A-Z) 
LOGICAL*1 REC1(KEYSIZ) , REC2 (KEYSIZ) 
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Example 20-1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a 
HP Fortran Program 


DO 20 I=1,KEYSIZ 
KOMPAR = REC1(I) - REC2(I) 
IF (KOMPAR .NE. 0) GOTO 50 


20 CONTINUE 
RETURN 

50 KOMPAR = ISIGN (1, KOMPAR) 
RETURN 
END 
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Example 20-2 is a HP Fortran program that demonstrates a sort operation using a file interface 
on input and a record interface on output. 


Example 20-2 Using SOR Routines to Sort Using Mixed Interface in a HP Fortran Program 


Program 


COCO AIA GAA OVA OO OVA AOA AAA GA AAA A Oa aA 


CHA A 


PROGRAM CALLSORT 


This is a sample Fortran program that calls the SOR 

routines using the file interface for input and the 

record interface for output. This program requests 

a record sort of the file ‘RO10SQ.DAT’ and writes 

the records to SYSSOUTPUT. The key is an 80-byte 

character ascending key starting in position 1 of 

each record. 

A short version of the input and output files follows: 

Input file R010SQ.DAT 
1 BBBBBBBBBB REST OF DATA IN RECORD... ...... cc cece ec ee ee eee eee ene END OF RECORD 
2 UUUUUUUUUU REST OF DATA IN RECORD...... cee eee END OF RECORD 
1 AAAAAAAAAA REST OF DATA IN RECORD... 1. eee ee ee ee eee END OF RECORD 
2 TITITITITY REST OP DATA: UN, RECORD |. o.:c-0:t-0: 0-0, deta stnactrare-acenanenacenereracineranacins END OF RECORD 
1 TITTTTITIT REST OF DATA IN RECORD occ. ove ee ace tte se a ates eee aa ae ae END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD........ eee eee END OF RECORD 
1 QQQ0000000 REST OF DATA IN RECORD... ..... cece ee ee eee ee eens END OF RECORD 
2 AAAAAAAAAA REST OF DATA IN RECORD....... cee eee END OF RECORD 
1 UUUUUUUUUU REST OF DATA IN RECORD... 2... ee ee ee ene END OF RECORD 
2 QQ00000000 REST OF DATA IN RECORD.............. cee eee eee ee eee END OF RECORD 
Output file SYSSOUTPUT 

1 AAAAAAAAAA REST OF DATA IN RECORD... . ee eee ee eee END OF RECORD 
1 BBBBBBBBBB REST OF DATA IN RECORD......... cc cece eee eee ee ee eens END OF RECORD 
1 QQQ00000000 REST OF DATA IN RECORD... 2... .. ee eee eee ee ee ens END OF RECORD 
1 TITTTTTTTT REST OF DATA IN RECORD... ...... cc ccc ee eee eee ees END OF RECORD 
1 UUUUUUUUUU REST OF DATA IN RECORD... 1... ee eee ee ees END OF RECORD 
2 AAAAAAAAAA REST OF DATA IN RECORD.......... eee eee END OF RECORD 
2 BBBBBBBBBB REST OF DATA IN RECORD........... cece eee END OF RECORD 
2 QQQ00000000 REST OF DATA IN RECORD........ cece eee eee eee END OF RECORD 
2 TITTTTTTTT REST OF DATA IN RECORD........... eee eee eee eee END OF RECORD 
2 UUUUUUUUUU REST OF DATA IN RECORD....... cece eee END OF RECORD 


Define external functions and data. 

CHARACTER*80 RECBUF 

CHARACTER*10 INPUTNAME !Input file name 
INTEGER*2 KEYBUF (5) !Key definition buffer 
INTEGER*4 SORSPASS FILES !SORT function names 


INTEGER* 4 SORSBEGIN SORT 

INTEGER*4 SORSSORT MERGE 

INTEGER*4 SORSRETURN REC 

INTEGER*4 SORSEND SORT 

INTEGER*4 ISTATUS !Storage for SORT function value 
EXTERNAL SS$_ENDOFFILE 

EXTERNAL DSCSK_DTYPE T 

EXTERNAL SORSGK_RECORD 

INTEGER*4 SRTTYPE 
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Example 20-2 (Cont.) Using SOR Routines to Sort Using Mixed Interface in a HP Fortran 
Program 


Initialize data -- first the file names, then the key buffer for 
one 80-byte character key starting in position 1, 3 work files, 
and a record sort process. 


Cop 1 > es @ as > i P| 


DATA INPUTNAME/'RO10SQ.DAT’ / 
KEYBUF(1) = 1 

KEYBUF (2) = %LOC(DSCSK_DTYPE T) 
KEYBUF (3) = 0 

KEYBUF (4) = 0 

KEYBUF (5) = 80 

SRTTYPE = %LOC(SORSGK_ RECORD) 


3 
4 
5 


Call the SORT -- each call is a function. 


Pass SORT the file names. 


OOO QA 


ISTATUS = SORSPASS FILES (INPUTNAME) 
IF (.NOT. ISTATUS) GOTO 10 


Initialize the work areas and keys. 


Ora 


ISTATUS = SORSBEGIN SORT(KEYBUF,,,,,,SRTTYPE, SREF (3) ) 
IF (.NOT. ISTATUS) GOTO 10 


Sort the records. 


aaa 


ISTATUS = SORSSORT MERGE( ) 
IF (.NOT. ISTATUS) GOTO 10 


Now retrieve the individual records and display them. 


WAAaAAA 


ISTATUS = SORSRETURN_REC (RECBUF) 

IF (.NOT. ISTATUS) GOTO 6 

ISTATUS = LIBSPUT_OUTPUT (RECBUF) 

GOTO 5 

IF (ISTATUS .EQ. %LOC(SS$ ENDOFFILE)) GOTO 7 
GOTO 10 


OV 


Clean up the work areas and files. 


hs Pe > a Ge 


ISTATUS = SORSEND SORT () 
IF (.NOT. ISTATUS) GOTO 10 
STOP ‘SORT SUCCESSFUL’ 

10 STOP ‘SORT UNSUCCESSFUL’ 
END 
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Example 20-3 is a HP Pascal program that demonstrates a merge operation using a file 
interface. 


Example 20-3 Using SOR Routines to Merge Three Input Files in a HP Pascal Program 


Program 


(* This program merges three input files, (IN_FILE.DAT, 
IN _FILE2.DAT IN FILE3.DAT), and creates one merged output file. *) 


program mergerecs( output, in _filel, in _file2, in file3, out_file )j; 


CONST 
SS$ NORMAL = 1; 
SS$ ENDOFFILE = %X870; 
SORSGK_RECORD = 1; 
SORSM_STABLE = 1; 
SORS$M_SEQ CHECK = 4; 
SORSM_SIGNAL = 8; 
DSC$K_DTYPE T = 14; 


TYPE 
SUBYTE = [BYTE] 0..255; 
SUWORD = [WORD] 0..65535; 


const 
num of keys 
merge order 
Irl 


i 
bh 
Wn. 
bh 


ascending 
descending 


"oul 
r= 


type 
key buffer _block= 
packed record 


key_ type: Suword; 
key order: Suword; 
key offset: Suword; 
key length: Suword; 
end; 


key buffer _type= 
packed record 


key count: Suword; 
blocks: packed array[1..num_of keys] of key buffer block; 
end; 

record buffer = packed array[1..lrl] of char; 


record buffer descr = 
packed record 
length: $Suword; 
dummy: $uword; 
addr: “record buffer; 
end; 
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Example 20-3 (Cont.) Using SOR Routines to Merge Three Input Files in a HP Pascal Program 


var 
in filel, 
in file2, 
in file3, 
out_file: text; 
key buffer: key buffer type; 
rec buffer: record buffer; 
rec_ length: S$uword; 


status: integer; 
1: integer; 
function sorsbegin_merge ( 

var buffer: key buffer type; 
lrl: Suword; 
mrg_options: integer; 
merge order: Subyte; 
simmed cmp rtn: integer := 0; 
simmed eql rtn: integer := 0; 


Simmed [unbound] function 
read_record ( 
var rec: record buffer descr; 
var filenumber: integer; 
var recordsize: Suword): integer 
): integer; extern; 


function sorSreturn_rec ( 
sstdescr rec: record buffer; 
var rec_size: Suword 
): integer; extern; 


function sor$end_sort: integer; extern; 
procedure sysSexit( %immed status : integer ); extern; 


function read_record ( 
var rec: record buffer descr; 
var filenumber: integer; 
var recordsize: Suword 


): integer; 
procedure readone( var filename: text ); 
begin 
recordsize := 0; 
if eof (filename) 
then 
read_record := ss$ endoffile 
else 
begin 
while not eoln(filename) and (recordsize < rec.length) do 
begin 
recordsize := recordsize + 1; 
read(filename,rec.addr“* [recordsize] ) ; 
end; 
readin (filename) ; 
end; 
end; 


(continued on next page) 
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Example 20-3 (Cont.) Using SOR Routines to Merge Three Input Files in a HP Pascal Program 


begin 
read_record := ss$ normal; 
case filenumber of 
1: readone(in filel) ; 
2: readone(in file2) ; 
3: readone(in file3) ; 
otherwise 
read_record := ss$ endoffile; 
end; 
end; 


procedure initfiles; 

begin 

open( in filel, ‘infilel.dat’, old ); 
open( in file2, ‘infile2.dat’, old ); 
open( in file3, ‘infile3.dat’, old ); 
open( out_file, ‘temp.tmp’ ); 

reset( in filel ); 

reset( in file2 ); 

reset ( in file3 ); 

rewrite( out file ); 

end; 


procedure error( status : integer ); 

begin 

writeln( ‘merge unsuccessful. status=%x', status:8 hex ); 
sysSexit (status) ; 

end; 

begin 


with key buffer do 

begin 

key count := 1; 

with blocks[1] do 
begin 
key_type := dsc$k_dtype t; 
key_order := ascending; 
key offset := 0; 


key_length := 5; 
end; 
end; 
initfiles; 
status := sorSbegin merge( key buffer, lrl, 
sor$m_seq check + sor$m_ signal, 
merge order, 0, 0, read_record ); 
repeat 
begin 
rec_length := 0; 
status := sor$return_rec( rec buffer, rec_length ); 
if odd(status) 
then 
begin 
for i := 1 to rec_length do write(out_file, rec _buffer[i]); 
writeln(out file); 
end; 
end 


until not odd(status) ; 


if status <> ss$ endoffile then error(status) ; 
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Example 20-3 (Cont.) Using SOR Routines to Merge Three Input Files in a HP Pascal Program 


status := sorSend_sort; 
if not odd(status) then error(status) ; 


writeln( ‘merge successful.’ ); 


end. 
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Example 20-4 is a HP Pascal program that demonstrates a sort operation using a record 


interface. 


Example 20-4 Using SOR Routines to Sort Records from Two Input Files in a HP Pascal 


Program 


Pascal Program 
PROGRAM FILETORECORDSORT (OUTPUT, SORTOUT) ; 


(* This program calls SOR routines to read and sort records from 
two input files, (PASINPUT1.DAT and PASINPUT2.DAT) and to return 
sorted records to this program to be written to the output file, 
(TEMP.TMP). *) 


(* Declarations for external status codes, and data structures, such as 


the types SUBYTE (an unsigned byte) and SUWORD (an unsigned word). 


CONST 
SS$ NORMAL = 1; 
SS$ ENDOFFILE = %X870; 
SORSGK_RECORD = 1; 
SORSM_STABLE = 1; 
SORS$M_SEQ CHECK = 4; 
SORSM_SIGNAL = 8; 
DSC$K_DTYPE T = 14; 


TYPE 
SUBYTE = [BYTE] 0..255; 
SUWORD = [WORD] 0..65535; 
CONST 
Numberofkeys = 1 ; (* Number of keys for this sort *) 
LRL = 131 ; (* Longest Record Length for output records *) 


(* Key orders *) 


Ascending = 0 ; 
Descending = 1 ; 


TYPE 
Keybufferblock= packed record 
Keytype : SUWORD ; 
Keyorder : SUWORD ; 
Keyoffset : SUWORD ; 
Keylength : SUWORD 
end ; 


(* The keybuffer. Note that the field buffer is a one-component array in 
this program. This type definition would allow a multikeyed sort. *) 


Keybuffer= packed record 
Numkeys : SUWORD ; 
Blocks : packed array[1..Numberofkeys] OF Keybufferblock 
end ; 


(* The record buffer. This buffer will be used to hold the returned 
records from SORT. *) 


Recordbuffer = packed array[1..LRL] of char ; 


(* Name type for input and output files. A necessary fudge for %stdescr 
mechanism. *) 


nametype= packed array[1..13] of char ; 


*) 


(continued on next page) 


Sort/Merge (SOR) Routines SOR-19 


Sort/Merge (SOR) Routines 
20.3 Using the SOR Routines: Examples 


Example 20-4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a HP 
Pascal Program 


VAR 
Sortout : text ; 
Buffer : Keybuffer ; 
Sortoptions : integer ; 
Sorttype : SUBYTE ; 
Numworkfiles : SUBYTE ; 
Status : integer ; 
Rec : Recordbuffer ; 
Recordlength : SUWORD ; 
Inputname: nametype ; 
i: integer ; 


the output file * 
the actual keybuffer *) 
flag for sorting options *) 
sorting process * 
number of work files *) 
function return status code *) 
a record buffer * 
the returned record length *) 
input file name * 
loop control variable *) 


a 


(* function and procedure declarations *) 


(* Declarations of SORT functions *) 

(* Note that the following SORT routine declarations 
do not use all of the possible routine parameters. *) 

(* The parameters used MUST have all preceding parameters specified, 
however. *) 


FUNCTION SORSPASS FILES 
(SSTDESCR Inname : nametype ) 
: INTEGER ; EXTERN ; 


FUNCTION SORSBEGIN_SORT ( 
VAR Buffer : Keybuffer ; 
Lrlen : SUWORD ; 
VAR Sortoptions : INTEGER ; 
SIMMED Filesize : INTEGER ; 
SIMMED Usercompare : INTEGER ; 
SIMMED Userequal : INTEGER ; 
VAR Sorttype : SUBYTE ; 
VAR Numworkfiles : SUBYTE ) 
: INTEGER ; EXTERN ; 


FUNCTION SORSSORT_ MERGE 
: INTEGER ; EXTERN ; 


FUNCTION SORSRETURN_REC ( 
SSTDESCR Rec : Recordbuffer ; 
VAR Recordsize : SUWORD ) 

: INTEGER ; EXTERN ; 


FUNCTION SORSEND_ SORT 
: INTEGER ; EXTERN ; 


(* End of the SORT function declarations *) 


(* The CHECKSTATUS routine checks the return status for errors. *) 
(* If there is an error, write an error message and exit via sysSexit *) 
PROCEDURE CHECKSTATUS( var status : integer ) ; 


procedure sysSexit( status : integer ) ; extern ; 


begin (* begin checkstatus *) 
if odd(status) then 
begin 
writeln( '’ SORT unsuccessful. Error status = ', status:8 hex ) ; 
SYSSEXIT( status ) ; 
end ; 
end ; (* end checkstatus *) 
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Example 20-4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a HP 
Pascal Program 


(* end function and routine declarations *) 


BEGIN (* begin the main routine *) 


(* Initialize data for one 8-byte character key, starting at record 
offset 0, 3 work files, and the record sorting process *) 


Inputname := ‘PASINPUT1.DAT’ ; 
WITH Buffer DO 
BEGIN 
Numkeys := 1; 
WITH Blocks[1] DO 
BEGIN 
Keytype := DSCSK DTYPE T ; (* Use OpenVMS descriptor data types to 
define SORT data types. *) 


Keyorder := Ascending ; 
Keyoffset := 0 ; 
Keylength := 8 ; 


END; 
END; 
Sorttype := SORSGK RECORD ; (* Use the global SORT constant to 
define the sort process. *) 
Sortoptions := SORSM STABLE ; (* Use the global SORT constant to 
define the stable sort option. *) 
Numworkfiles := 3 ; 


* call the sort routines as a series of functions *) 


* pass the first filename to SORT *) 
Status := SORSPASS FILES( Inputname ) ; 


* Check status for error. *) 
CHECKSTATUS( Status ) ; 


* pass the second filename to SORT *) 
Inputname := ‘PASINPUT2.DAT’ ; 


Status := SORSPASS FILES( Inputname ) ; 


* Check status for error. *) 
CHECKSTATUS( Status ) ; 


* initialize work areas and keys *) 
Status := SORSBEGIN SORT( Buffer, 0, Sortoptions, 0, 0, 0, 
Sorttype, Numworkfiles ) 


* Check status for error. *) 
CHECKSTATUS( Status ) ; 


* sort the records *) 
Status := SORSSORT_MERGE Hi 


* Check status for error. *) 
CHECKSTATUS( Status ) ; 


* Ready output file for writing returned records from SORT. *) 
OPEN( SORTOUT, 'TEMP.TMP’ ) ; 
REWRITE( SORTOUT ) ; 


* Now get the sorted records from SORT. *) 
Recordlength := 0 ; 

REPEAT 

Status := SORSRETURN REC( Rec, Recordlength ) ; 
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Example 20-4 (Cont.) Using SOR Routines to Sort Records from Two Input Files in a HP 
Pascal Program 


if odd( Status ) 


then (* if successful, write record to output file. *) 
begin 
for i := 1 to Recordlength do 
write( sortout, Rec[i] ) ; (* write each character *) 
writeln (sortout) ; (* end output line *) 
end; 


UNTIL not odd( Status ) ; 


(* If there was just no more data to be returned (eof) continue, otherwise 
exit with an error. *) 
if Status <> SS$ ENDOFFILE then 
CHECKSTATUS( Status ) ; 


(* The sort has been successful to this point. *) 


(* Close the output file *) 
CLOSE( sortout ) ; 


(* clean up work areas and files *) 
Status := SORSEND SORT ; 


(* Check status for error. *) 
CHECKSTATUS( Status ); 


WRITELN ('SORT SUCCESSFUL’) ; 
END. 
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Example 20-5 is a HP C program that demonstrates a sort operation using the STABLE option 
and two test keys. 


Example 20-5 Using SOR Routines to Sort Records Using the STABLE Option and Two Text 
Keys in a HP C Program 


/* 
C Program Example 


This program demonstrates the use of the STABLE option 

with 2 ascending text keys to sort a file of names. 

The names are sorted by the first 6 characters of the last 

name and the first 6 characters of the first name. 

The contents of the input file and resulting output file 

are listed below. The associated C program code listing follows. 


Input file: example.in 


JONES DAVID 
WARNER LIZZY 
SMITTS JAMES 
SMITH RANDY 
BROWN TONY 
GRANT JOSEPH 
BROWN JAMES 
JONES DAVID 
BAKER PAMELA 
SMART SHERYL 
RUSSO JOSEPH 
JONES DONALD 
BROWN GORDON 


Output file: example.out 


BAKER PAMELA 
BROWN GORDON 
BROWN JAMES 
BROWN ‘TONY 
GRANT JOSEPH 
JONES DAVID 
JONES DAVID 
JONES DONALD 
RUSSO JOSEPH 
SMART SHERYL 
SMITH RANDY 
SMITTS JAMES 
WARNER LIZZY 
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Example 20-5 (Cont.) Using SOR Routines to Sort Records Using the STABLE Option and 


/* 


*Rekoe oe ee ee ee ee ee ee ee ee ee ee ee ee ee ee eee ee eee eee eee 


kk 


Two Text Keys in a HP C Program 


** EXAMPLE.C code: 


kk 


** Abstract: Example of using sort with the STABLE option and 


kk 
kk 
kk 


** Input 


2 text keys (both ascending) . 


file: example.in 


** Output file: example.out 


** Include files: 


include 
include 
include 
include 
include 
include 


<stdlib.h> 
<stdio.h> 
<string.h> 
<descrip.h> 
<ssdef .h> 
<sor$Sroutines.h> 


** Local macro definitions: 


wi 


# define MAX REC LEN 150 
# define MAX NUM KEYS 10 


/* Stindedece ceded sSsiaaecia acess ce mie Sjeale Oeics else a alee a ei ai at a ee ei ciieticis 


** Local structure definitions. 


*/ 


/* Define 


the description for each key. */ 


typedef struct { 


unsigned short type; /* Data type of key */ 
unsigned short order; /* Order of key */ 
unsigned short offset; /* Offset of key */ 
unsigned short len; /* Length of key */ 
} key_info; 

struct 
unsigned short num; /* number of keys */ 
key info key [MAX NUM KEYS] ; 

} key buffer; 

/* Beet Stee ec ede See eee eee ais Sie aS SiS Sr eS Seine Seeing ote ee eet ee 

** External literals. 

*/ 

globalvalue 


int 


SORSM_STABLE; 
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Example 20-5 (Cont.) Using SOR Routines to Sort Records Using the STABLE Option and 
Two Text Keys in a HP C Program 


/* en ee a 
** Main entry point. 
* 
/ 
main (int argc, char *argv[]) 
int a 
unsigned int options; /* Sort options */ 
unsigned int num_records in; 
unsigned int num_ records out; 
unsigned int lrl; /* longest record length */ 
unsigned short size; /* record size from return_rec */ 
unsigned int status; 
unsigned long int return_status; 
FILE *infile; /* input file */ 
FILE *outfile; /* output file */ 
char record [MAX _REC_LEN] ; 
SDESCRIPTOR (record desc, record) ; 
lrl = sizeof (record) ; 
key _buffer.num = 2° 
key buffer.key[0] .type = DSC$K_DTYPE T; 
key buffer.key[0] .order = 0; /* ascending */ 
key buffer.key[0] .offset = 0; 
key buffer.key[0] .len = by 
key _buffer.key[1] .type = DSC$K_DTYPE T; 
key buffer.key[1] .order = 0; /* ascending */ 
key buffer.key [1] .offset = 7 
key buffer.key[1] .len = 6; 
/* Open input and output files. */ 


if (arge != 3) 


printf ("Usage: example inputfile outputfile\n"); 


exit (-1); 
infile = fopen(argv[1], "r"); 
if (infile == (FILE *) NULL) 


printf ("Can't open input file %s\n",argv[1]); 
exit (-1); 


outfile = fopen(argv[2], "w"); 
if (outfile == (FILE *) NULL) 


printf ("Can't create output file %s\n",argv[2]); 
exit (-1); 


(continued on next page) 
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Example 20-5 (Cont.) Using SOR Routines to Sort Records Using the STABLE Option and 
Two Text Keys in a HP C Program 


/* Specify options. Initialize the sort and check for errors. */ 


options = SORSM_ STABLE; 
return_status = SORSBEGIN SORT(&key buffer, &lrl, &options, 0,0,0,0,0,0); 
if (return_status != SS$ NORMAL) 


printf ("Status from SORSBEGIN SORT: 0x%x\n", return_status) ; 
exit (return_status) ; 


/* Within a loop, get all the records from the input file. */ 
/* Exit if an error occurs. */ 


num records in = 0; 
while (fgets( record, lrl, infile) != NULL) 


record desc.dsc$w_length = strlen(record) -1; 
num records in++; 

return status = SORSRELEASE REC(&record_desc, 0) ; 
if (return_status != SS$ NORMAL) 


printf ("Status from SORSRELEASE REC: 0x%x\n", return_status) ; 
exit (return_status) ; 


} 


/* Sort all of the input records. */ 
/* Exit if an error occurs. */ 


return_status = SORSSORT MERGE (0) ; 
if (return_status != SS$ NORMAL) 


printf ("Status from SORSSORT MERGE: 0x%x\n", return_status) ; 
exit (return_status) ; 


/* Within a loop, write the sorted records to the output file. */ 
/* Exit if an error occurs, other than end-of-file. */ 


record desc.dsc$w_ length = lrl; 

num records out = 0; 

do 
return_status = SORSRETURN REC(&record_ desc, &$ize, 0) ; 
if (return_status == SS$ NORMAL) 


num_records out++; 
status = fprintf (outfile,"%.*s\n", size, record); 
if (status < 0 ) 


printf ("Error writing to output file, status = %d\n", status); 
exit (status) ; 


} 


else 
if (return_status != SS$ ENDOFFILE) 


printf ("Status from SORSRETURN REC: 0x%x\n", return_status) ; 
exit (return_status) ; 


} while (return_status != SS$ ENDOFFILE) ; 


(continued on next page) 
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20.3 Using the SOR Routines: Examples 


Example 20-5 (Cont.) Using SOR Routines to Sort Records Using the STABLE Option and 


Two Text Keys in a HP C Program 


/* Sanity check - assure number of input and output records match. */ 
if (num_records out != num_records_ in) 
printf ("Number of records out is not correct. # in = %d, # out = %d\n", 


num records out, num records in) ; 
exit (status) ; 


/* Successful completion. Close input and output files. End program. */ 
return_status = SORSEND SORT(0) ; 
if (return_status != SS$ NORMAL) 


printf ("Status from SORSEND SORT: 0x%x\n", return_status) ; 
exit (return_status) ; 


fclose (infile) ; 
fclose (outfile); 


20.4 SOR Routines 


This section describes the individual SOR routines. 
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SOR$BEGIN_MERGE—Initialize a Merge Operation 


The SOR$BEGIN_ MERGE routine initializes the merge operation by opening 
the input and output files and by providing the number of input files, the key 
specifications, and the merge options. 


Format 
SOR$BEGIN_ MERGE _[key-buffer] [,Irl] [options] [, merge_order] [,user_compare] 
[,user_equal] [,user_input] [,context] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most Sort/Merge utility routines return a condition 
value in RO. Condition values that this routine can return are listed under 
Condition Values Returned. 
Arguments 
key_buffer 
OpenVMS usage: vector_word_unsigned 
type: word (unsigned) 
access: read only 
mechanism: by reference 


Array of words describing the keys on which you plan to merge. The key_buffer 
argument is the address of an array containing the key descriptions. 


The first word of this array contains the number of keys described (up to 255). 
Following the first word, each key is described (in order of priority) in blocks of 
four words. The four words specify the key’s data type, order, offset, and length, 
respectively. 


The first word of the block specifies the key’s data type. The following data types 
are accepted: 


DSC$K_DTYPE_Z Unspecified (uninfluenced by collating 
sequence) 
DSC$K_DTYPE B Byte integer (signed) 
DSC$K_DTYPE_BU Byte (unsigned) 
DSC$K_DTYPE_W Word integer (signed) 
DSC$K_DTYPE_WU Word (unsigned) 
DSC$K_DTYPE_L Longword integer (signed) 
DSC$K_DTYPE_LU Longword (unsigned) 
DSC$K_DTYPE_Q Quadword integer (signed) 
DSC$K_DTYPE_QU Quadword (unsigned) 
DSC$K_DTYPE_Ot Octaword integer (signed) 


tData type is not currently supported by the high-performance Sort/M erge utility. 
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DSC$K_DTYPE_OUt Octaword (unsigned) 
DSC$K_DTYPE_F Single-precision floating 
DSC$K_DTYPE_D Double-precision floating 
DSC$K_DTYPE_G G-format floating 
DSC$K_DTYPE_Ht H-format floating 
DSC$K_DTYPE_FS+t IEEE single-precision S floating 
DSC$K_DTYPE_FT#¥ IEEE doubleprecision T floating 
DSC$K_DTYPE_T Text (may be influenced by collating 
sequence) 
DSC$K_DTYPE_NU Numeric string, unsigned 
DSC$K_DTYPE_NL Numeric string, left separate sign 
DSC$K_DTYPE_NLO Numeric string, left overpunched sign 
DSC$K_DTYPE_NR Numeric string, right separate sign 
DSC$K_DTYPE_NRO Numeric string, right overpunched sign 
DSC$K_DTYPE_NZt Numeric string, zoned sign 
DSC$K_DTYPE_P Packed decimal string 


tData type is not currently supported by the high-performance Sort/M erge utility. 

#Data type is Alpha specific. 

The HP OpenVMS Programming Concepts Manual manual describes each of 
these data types. 


The second word of the block specifies the key order: 0 for ascending order, 1 for 
descending order. The third word of the block specifies the relative offset of the 
key in the record. (Note that the first byte in the record is at position 0.) The 
fourth word of the block specifies the key length in bytes (in digits for packed 
decimal—DSC$K_DTYPE_P). 


If you do not specify the key_buffer argument, you must pass either a key 
comparison routine or use a specification file to define the key. 


Irl 
OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: read only 
mechanism: by reference 


Length of the longest record that will be released for merging. The Irl (longest 
record length) argument is the address of a word containing the length. If the 
input file is on a disk, this argument is not required. It is required when you use 
the record interface. For Vertical Format Control (VFC) records, this length must 
include the length of the fixed-length portion of the record. 


options 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags that identify merge options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. 
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The following table lists and describes the bit mask values available: 


Flag Description 

SOR$M_STABLE Keeps records with equal keys in the same order as 
they appeared on input. 

SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC 
collating sequence. No translation takes place. 

SOR$M_ MULTI Orders character keys according to the multinational 


collating sequence, which collates the international 
character set. 

SOR$M_NOSIGNAL Returns a status code instead of signaling errors. 

SOR$M_NODUPS Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 

SOR$M_SEQ CHECK Requests an “out of order” error return if an input file 
is not already in sequence. By default, this check is 
not done. You must request sequence checking if you 
specify an equal-key routine. 


All other bits in the longword are reserved and must be zero. 


merge_order 
OpenVMS usage: byte _unsigned 


type: byte (unsigned) 
access: read only 
mechanism: by reference 


Number of input streams to be merged. The merge_order argument is the 
address of a byte containing the number of files (1 through 10) to be merged. 
(The high-performance Sort/M erge utility allows you to specify 1 through 12 files.) 
When you use the record interface on input, this argument is required. 


user_compare 
OpenVMS usage: procedure 


type: procedure value 
access: function call 
mechanism: by reference 


Routine that compares records to determine their merge order. (This routine is 
not currently supported by the high-performance Sort/Merge utility.) The user_ 
compare argument is the address of the procedure value for this user-written 
routine. If you do not specify the key_buffer argument or if you define key 
information in a specification file, this argument is required. 


MERGE calls the comparison routine with five reference arguments—ADRSI1, 
ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses of the two 
records to be compared, the lengths of these two records, and the context 
longword. 


The comparison routine must return a 32-bit integer value: 
e -1if the first record collates before the second 
¢ Oif the records collate as equal 


e 1if the first record collates after the second 
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user_equal 

OpenVMS usage: procedure 

type: procedure value 
access: function call 
mechanism: by reference 


Routine that resolves the merge order when records have duplicate keys. (This 
routine is not currently supported by the high-performance Sort/M erge utility.) 
The user_equal argument is the address of the procedure value for this user- 
written routine. If you specify SOR$M_ STABLE or SOR$M_NODUPS in the 
options argument, do not use this argument. 


MERGE calls the duplicate key routine with five reference arguments—ADRS1, 
ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses of the two 
records that compare equally, the lengths of the two records that compare equally, 
and the context longword. 


The routine must return one of the following 32-bit condition codes: 


Code Description 


SOR$ DELETE1 Delete the first record from the merge. 
SOR$ DELETE2 Delete the second record from the merge. 
SOR$ DELBOTH Delete both records from the merge. 
SS$ NORMAL Keep both records in the merge. 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


user_input 

OpenVMS usage: procedure 

type: procedure value 
access: function call 
mechanism: by reference 


Routine that releases records to the merge operation. The user_input argument 
is the address of the procedure value for this user-written routine. SOR$BEGIN_ 
MERGE and SOR$RETURN _REC call this routine until all records have been 
passed. 


This input routine must read (or construct) a record, place it in a record buffer, 
store its length in an output argument, and then return control to MERGE. 


The input routine must accept the following four arguments: 
e A descriptor of the buffer where the routine must place the record 


e A longword, passed by reference, containing the stream number from which 
to input a record (the first file is 1, the second 2, and so on) 


e« A word, passed by reference, where the routine must return the actual length 
of the record 


e The context longword, passed by reference 
The input routine must also return one of the following status values: 


e SS$ NORMAL or any other success status causes the merge operation to 
continue. 
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Description 


e SS$ ENDOFFILE indicates that no more records are in the file. The contents 
of the buffer are ignored. 


e Any other error status terminates the merge operation and passes the status 
value back to the caller of SORSBEGIN_ MERGE or SOR$RETURN_REC. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value that was supplied by SORT/MERGE. 


The SOR$BEGIN_MERGE routine initializes the merge process by passing 
arguments that provide the number of input streams, the key specifications, and 
any merge options. 


You must define the key by passing either the key buffer address argument 
or your own comparison routine address. (You can also define the key in a 
specification file and call the SOR$SPEC_FILE routine.) 


The SOR$BEGIN_ MERGE routine initializes the merge process in the file, 
record, and mixed interfaces. For record interface on input, you must also pass 
the merge order, the input routine address, and the longest record length. For 
files not on disk, you must pass the longest record length. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 


Condition Values Returned 


SS$ NORMAL Success. 

SOR$ BADDTYPE Invalid or unsupported CDD data type. 

SOR$ BADLENOFF Length and offset must be multiples of 8 bits. 
SOR$ BADLOGIC Internal logic error detected. 

SOR$ BADOCCURS Invalid OCCURS clause. 

SOR$ BADOVRLAY Invalid overlay structure. 

SOR$ BADPROTCL Node is an invalid CDD object. 

SOR$ BAD KEY Invalid key specification. 

SOR$ BAD _LRL Record length n greater than specified longest 


record length. 


SOR-32 Sort/Merge (SOR) Routines 


SOR$ BAD_MERGE 


SOR$ BAD_ORDER 
SOR$ BAD_SRL 
SOR$ BAD_TYPE 
SOR$ _CDDERROR 
SOR$ CLOSEIN 
SOR$ CLOSEOUT 
SOR$ COL_CHAR 
SOR$_COL_CMPLX 
SOR$ COL_PAD 
SOR$ COL_THREE 
SOR$ ENDDIAGS 
SOR$_ILLBASE 
SOR$ ILLLITERL 


SOR$_ILLSCALE 
SOR$_INCDIGITS 


SOR$_INCNODATA 
SOR$_INCNOKEY 


SOR$ IND_OVR 
SOR$ KEYAMBINC 
SOR$ KEYED 


SOR$ KEY_LEN 
SOR$ LRL_MISS 
SOR$ MISLENOFF 
SOR$ MISS PARAM 
SOR$ MULTIDIM 
SOR$ NODUPEXC 


SOR$ NOTRECORD 
SOR$ NUM_KEY 
SOR$_NYI 
SOR$_OPENIN 
SOR$ OPENOUT 
SOR$ READERR 
SOR$ RTNERROR 
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Number of input files must be between 0 and 10. 
(For the high-performance Sort/Merge utility, the 
maximum number is 12.) 


Merge input is out of order. 

Record length n is too short to contain keys. 
Invalid sort process specified. 

CDD error at node name 

Error closing file as input. 

Error closing file 

Invalid character definition. 
Collating sequence is too complex. 
Invalid pad character. 

Cannot define 3-byte collating values. 
Completed with diagnostics. 
Nondecimal base is invalid. 


Record containing symbolic literals is 
unsupported. 


Nonzero scale invalid for floating-point data item. 


Number of digits is not consistent with the type 
or length of item. 


Include specification references no data, at line 
n. 


Include specification references no keys, at line 
n. 


Indexed output file must already exist. 

Key specification is ambiguous or inconsistent. 
Mismatch between SORT/MERGE keys and 
primary file key. 

Invalid key length, key number n, length n. 
Longest record length must be specified. 
Length and offset required. 

A required subroutine argument is missing. 
Invalid multidimensional OCCURS. 


Equal-key routine and no-duplicates option 
cannot both be specified. 


Node nameis a name, not a record definition. 
Too many keys specified. 

Not yet implemented. 

Error opening file as input. 

Error opening file as output. 

Error reading file 


Unexpected error status from user-written 
routine. 


Sort/Merge (SOR) Routines SOR-33 


Sort/Merge (SOR) Routines 
SOR$BEGIN_MERGE 


SOR$_SIGNCOMPQ 


SOR$ SORT_ON 
SOR$ SPCIVC 
SOR$ SPCIVD 
SOR$_SPCIVF 
SOR$_SPCIVI 
SOR$ SPCIVK 
SOR$_SPCIVP 
SOR$ SPCIVS 
SOR$_SPCIVX 
SOR$ SPCMIS 
SOR$ SPCOVR 
SOR$ SPCSIS 
SOR$ SRTIWA 


SOR$ STABLEEX 


SOR$ SYSERROR 
SOR$ UNDOPTION 
SOR$ UNSUPLEVL 
SOR$ WRITEERR 
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Absolute Date and Time data type represented in 
1-second units. 


Sort or merge routines called in incorrect order. 
Invalid collating sequence specification at line n. 
Invalid data type at line n. 

Invalid field specification at linen. 

Invalid include or omit specification at line n. 
Invalid key or data specification at line n. 
Invalid sort process at line n. 

Invalid specification at line n. 

Invalid condition specification at line n. 

Invalid merge specification at line n. 
Overridden specification at line n. 

Invalid sort specification at line n. 


Insufficient space. The specification file is too 
complex. 


E qual-key routine and stable option cannot both 
be specified. 

System service error. 

Undefined option flag was set. 

Unsupported core level for record name 

Error writing file 
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SOR$BEGIN_SORT—Begin a Sort Operation 


Format 


Returns 


Arguments 


The SOR$BEGIN_ SORT routine initializes a sort operation by opening input and 
output files and by passing the key information and any sort options. 


SOR$BEGIN_SORT  [key_buffer] [,Irl] [,options] [,file_alloc] [,user_compare] 
[,user_equal] [,sort_process] [,work_files] [,context] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


key_buffer 

OpenVMS usage: vector_word_unsigned 
type: word (unsigned) 
access: read only 

mechanism: by reference 


Array of words describing the keys on which you plan to sort. The key_buffer 
argument is the address of an array containing the key descriptions. 


The first word of this array contains the number of keys described (up to 255). 
Following the first word, each key is described (in order of priority) in blocks of 
four words. The four words specify the key’s data type, order, offset, and length, 
respectively. 


The first word of the block specifies the data type of the key. The following data 
types are accepted: 


DSC$K_DTYPE Z Unspecified (uninfluenced by collating 
sequence) 
DSC$K_DTYPE B Byte integer (signed) 
DSC$K_DTYPE_BU Byte (unsigned) 
DSC$K_DTYPE_W Word integer (signed) 
DSC$K_DTYPE_WU Word (unsigned) 
DSC$K_DTYPE_L Longword integer (signed) 
DSC$K_DTYPE_LU Longword (unsigned) 
DSC$K_DTYPE_Q Quadword integer (signed) 
DSC$K_DTYPE_QU Quadword (unsigned) 
DSC$K_DTYPE_Ot Octaword integer (signed) 


tData type is not currently supported by the high-performance Sort/Merge utility. 
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DSC$K_DTYPE_OUt Octaword (unsigned) 
DSC$K_DTYPE_F Single-precision floating 
DSC$K_DTYPE_D Double-precision floating 
DSC$K_DTYPE_G G-format floating 
DSC$K_DTYPE_Ht H-format floating 
DSC$K_DTYPE_FS# IEEE single-precision S floating 
DSC$K_DTYPE_FT¥ IEEE doubleprecision T floating 
DSC$K_DTYPE_T Text (may be influenced by collating 
sequence) 
DSC$K_DTYPE_NU Numeric string, unsigned 
DSC$K_DTYPE_NL Numeric string, left separate sign 
DSC$K_DTYPE_NLO Numeric string, left overpunched sign 
DSC$K_DTYPE_NR Numeric string, right separate sign 
DSC$K_DTYPE_NRO Numeric string, right overpunched sign 
DSC$K_DTYPE_NZt Numeric string, zoned sign 
DSC$K_DTYPE_P Packed decimal string 


tData type is not currently supported by the high-performance Sort/M erge utility. 
+Data type is Alpha specific. 


The HP OpenVMS Programming Concepts Manual describes each of these data 
types. 


The second word of the block specifies the key order: O for ascending order, 1 
for descending order. The third word of the block specifies the relative offset of 
the key in the record. Note that the first byte in the record is at position 0. The 
fourth word of the block specifies the key length in bytes (in digits for packed 
decimal—DSC$K_DTYPE _P). 


The key_buffer argument specifies the address of the key buffer in the data 
area. If you do not specify this argument, you must either pass a key comparison 
routine or use a specification file to define the key. 


Irl 
OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: read only 
mechanism: by reference 


Length of the longest record that will be released for sorting. The Irl argument 
is the address of a word containing the length. This argument is not required if 
the input files are on disk but is required when you use the record interface. For 
VFC records, this length must include the length of the fixed-length portion of the 


record. 

options 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Flags that identify sort options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. The 
following table lists and describes the bit mask values available. 
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Flags Description 


SOR$M_STABLE Keeps records with equal keys in the same order in 
which they appeared on input. With multiple input files 
that have records that collate as equal, records from the 
first input file are placed before the records from the 
second input file, and so on. 


SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC 
collating sequence. No translation takes place. 
SOR$M_MULTI Orders character keys according to the multinational 


collating sequence, which collates the international 
character set. 
SOR$M_NOSIGNAL Returns a status code instead of signaling errors. 


SOR$M_NODUPS Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 


All other bits in the longword are reserved and must be zero. 


file_alloc 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Input file size in blocks. The file_alloc argument is the address of a longword 
containing the size of the input file. This argument is optional because, by 
default, SORT uses the allocation of the input files. If you are using the record 
interface, or if the input files are not on disk, the default is 1000 blocks.(The 
high-performance Sort/Merge utility determines the default based on the size 
of the input file, or if input is not from files, on available memory.) When you 
specify the input size with this argument, it overrides the default size. 


This optional argument is useful when you are using the record interface and you 
have a good idea of the total input size. You can use this argument to improve 
the efficiency of the sort by adjusting the amount of resources the sort process 
allocates to match the input size. 


user_compare 
OpenVMS usage: procedure 


type: procedure value 
access: function call 
mechanism: by reference 


User-written routine that compares records to determine their sort order. (This 
argument is not currently supported by the high-performance Sort/M erge utility.) 
The user_compare argument is the address of the procedure value for this 
user-written routine. If you do not specify the key_buffer argument or if you 
define key information in a specification file, this argument is required. 


SORT/MERGE calls the comparison routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses of the 
two records to be compared, the lengths of these two records, and the context 
longword. The LENG1 and LENG2 arguments are addresses that point to 16-bit 
word structures that contain the length information. 
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The comparison routine must return a 32-bit integer value: 
e -1if the first record collates before the second 

¢ Oif the records collate as equal 

e 1if the first record collates after the second 


user_equal 

OpenVMS usage: procedure 

type: procedure value 
access: function call 
mechanism: by reference 


User-written routine that resolves the sort order when records have duplicate 
keys. (This argument is not currently supported by the high-performance 
Sort/Merge utility.) The user_equal argument is the address of the procedure 
value for this user-written routine. If you specify SOR$M_STABLE or SOR$M _ 
NODUPS in the options argument, do not use this argument. 


SORT/MERGE calls the duplicate key routine with five reference arguments— 
ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding to the addresses 

of the two records that compare equally, the lengths of the two records that 
compare equally, and the context longword. The LENG1 and LENG2 arguments 
are addresses that point to 16-bit word structures that contain the length 
information. 


The routine must return one of the following 32-bit integer condition codes: 


Code Description 


SOR$ DELETE1 Delete the first record from the sort. 
SOR$ DELETE2 Delete the second record from the sort. 
SOR$ DELBOTH Delete both records from the sort. 
SS$ NORMAL Keep both records in the sort. 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


sort_process 
OpenVMS usage: byte unsigned 


type: byte (unsigned) 
access: read only 
mechanism: by reference 


Code indicating the type of sort process. The sort_process argument is the 
address of a byte whose value indicates whether the sort type is record, tag, 
index, or address. (The high-performance Sort/Merge utility supports only the 
record process. Implementation of the tag, address, and index processes is 
deferred to a future OpenVMS Alpha release.) The default is record. If you select 
the record interface on input, you can use only a record sort process. 


To specify a byte containing the value for the type of sort process you want, enter 
one of the following: 


e SOR$GK_RECORD (record sort) 
e SOR$GK_TAG (tag sort) 
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e SOR$GK_ADDRESS (address sort) 
e SOR$GK_INDEX (index sort) 


work_files 

OpenVMS usage: byte _unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


Number of work files to be used in the sorting process. The work_files argument 
is the address of a byte containing the number of work files; permissible values 
for SORT range from 0 through 10. (For the high-performance Sort/Merge utility, 
you can specify from 1 through 255 work files. The default is 2.) 


By default, SORT creates two temporary work files when it needs them and 
determines their size from the size of your input files. By increasing the number 
of work files, you can reduce their individual size so that each fits into less disk 
space. You can also assign each of them to different disk-structured devices 
(highly recommended). 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


The SOR$BEGIN_SORT routine initializes the sort process by setting up sort 
work areas and provides key specification and sort options. 


Specify the key information with the key_buffer argument, with the user_ 
compare argument, or in a specification file. If no key information is specified, 
the default (character for the entire record) is used. 


You must use the SOR$BEGIN_SORT routine to initialize the sort process for the 
file, record, and mixed interfaces. For record interface on input, you must use the 
Irl (longest record length) argument. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 


SS$ NORMAL 
SOR$ BADLOGIC 
SOR$ BAD_KEY 
SOR$ BAD_LRL 


SOR$ BAD_MERGE 


SOR$ BAD_TYPE 
SOR$ ENDDIAGS 
SOR$_INSVIRMEM 
SOR$ KEYAMBINC 
SOR$_KEY_LEN 
SOR$ LRL_MISS 
SOR$ NODUPEXC 


SOR$ NUM_KEY 
SOR$_NYI 
SOR$ RTNERROR 


SOR$_SORT_ON 
SOR$ STABLEEXC 


SOR$ SYSERROR 
SOR$ UNDOPTION 
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Normal successful completion. 
Internal logic error detected. 
Invalid key specification. 


Record length n greater than specified longest 
record length. 


Number of work files must be between 0 and 10. 
(For the high-performance Sort/Merge utility, the 
maximum number is 255.) 


Invalid sort process specified. 

Completed with diagnostics. 

Insufficient virtual memory. 

Key specification is ambiguous or inconsistent. 
Invalid key length, key number n, length n. 
Longest record length must be specified. 


Equal-key routine and no-duplicates option 
cannot both be specified. 


Too many keys specified. 
Not yet implemented. 


Unexpected error status from user-written 
routine. 


Sort or merge routine called in incorrect order. 
E qual-key routine and stable option cannot both 
be specified. 

System service error. 

Undefined option flag was set. 
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SOR$DTYPE—Define Data Type 


Format 


Returns 


Arguments 


The SOR$DTYPE routine defines a key data type that is not normally supported 
by SORT/MERGE. (This routine is not currently supported by the high- 
performance Sort/Merge utility.) This routine returns a key data type code that 
can be used in the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_ 
MERGE to describe special key data types (such as extended data types and 
National character set (NCS) collating sequences). 


SOR$DTYPE [context] ,dtype_code ,usage ,p1 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


dtype_code 

OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Returned key data type code. The dtype_code argument is the address of a word 
into which SORT/MERGE writes the key data type code that can be used in the 
key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_ MERGE. 
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SOR$DTYPE 
usage 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Description 


Address of a longword containing a code that indicates the interpretation of the 
pl argument. The following table lists and describes the valid usage codes: 


Flag Description 


SOR$K_ROUTINE The p1 argument should be interpreted as the 
address of the procedure value of a routine 
that SORT/MERGE will call to compare keys 
described by the dtype_code returned by the 
call to SOR$DTYPE. 


SOR$K_NCS TABLE The p1 argument should be interpreted as the 
address of a collating sequence identification 
returned by a call to NCS$GET_CS. SORT/MERGE 
will use this collating sequence to compare keys 
described by the dtype_code returned by the call to 
SOR$DTYPE. 


If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine with five 
reference arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX—corresponding 
to the addresses of the two keys to be compared, the lengths of the two keys, and 
the context longword. 


The comparison routine must return a 32-bit integer value: 
e -1lif the first key collates before the second 

¢ Oif the keys collate as equal 

e +1 if the first key collates after the second 


p1 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Address of the procedure value of a routine or the address of a collating sequence 
identification, depending on the usage argument. 


Call SOR$DTYPE to define a key data type not normally supported by 
SORT/MERGE. 


If your SORT/MERGE application needs to compare dates (for example) that are 
stored in text form and that is the only key in the records, then use the user_ 
compare argument to SOR$BEGIN_ SORT or SOR$BEGIN_ MERGE. However, if 
the records contain several keys besides the dates in text form, it may be easier 
to call SORS$DTYPE to allocate a key data type code that can then be used in the 
the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_ MERGE. 
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If your SORT/MERGE application has a string key that should be collated by a 
collating sequence defined by the NCS utility, the NCS$GET_CS routine can be 
used to fetch the collating sequence definition, and SOR$DTYPE can be called 
to allocate a key data type code for the collating sequence. This key data type 
code can then be used to describe keys that should be compared by this collating 
sequence. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 
SOR$ NYI Not yet implemented. 
SOR$ SORT_ON Sort or merge routine called in incorrect order. 
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SOR$END_SORT—End a Sort Operation 


The SOR$END_SORT routine performs cleanup functions, such as closing files 
and releasing memory. 


Format 
SOR$END_SORT [context] 

Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 
context 
OpenVMS usage: context 
type: longword 
access: write only 
mechanism: by reference 
Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 

Description 


The SOR$END_SORT routine ends a sort or merge operation, either at the end 
of a successful process or between calls because of an error. If an error status is 
returned, you must call SOR$¢END_ SORT to release all allocated resources. In 
addition, this routine can be called at any time to close files and release memory. 


The value of the optional context argument is cleared when the SOR$END_SORT 
routine completes its operation. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 


SS$ NORMAL Normal successful completion. 

SOR$ CLOSEIN Error closing file as input. 

SOR$ CLOSEOUT Error closing file as output. 

SOR$ ENDDIAGS Completed with diagnostics. 

SOR$ END SORT SORT/MERGE terminated, context = context. 
SOR$ SYSERROR System service error. 
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SOR$PASS_FILES—Pass File Name 


Format 


Returns 


Arguments 


The SOR$PASS FILES routine passes the names of input and output files and 
output file characteristics to SORT or MERGE. 


SOR$PASS FILES [inp desc] [,out_desc] [,org] [,rfm] [,bks] [,bls] [,mrs] [,alq] [,fop] 
[,fsz] [,context] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


inp_desc 

OpenVMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


Input file specification. The inp_desc argument is the address of a descriptor 
pointing to the file specification. In the file interface, you must call SOR$PASS _ 
FILES to pass SORT the input file specifications. For multiple input files, call 
SOR$PASS FILES once for each input file, passing one input file specification 
descriptor each time. 


In the mixed interface, if you are using the record interface on input, pass only 
the output file specification; do not pass any input file specifications. If you are 
using the record interface on output, pass only the input file specifications; do not 
pass an output file specification or any of the optional output file arguments. 


out_desc 

OpenVMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


Output file specification. The out_desc argument is the address of a descriptor 
pointing to the file specification. In the file interface, when you call SOR$PASS _ 
FILES, you must pass the output file specification. Specify the output file 
specification and characteristics only once, as part of the first call, as in the 
following: 

Call SORSPASS FILES (Input1, Output) 


Call SORSPASS FILES (Input2) 
Call SORSPASS FILES (Input3) 
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In the mixed interface, if you are using the record interface on input, pass only 
the output file specification; do not pass any input file specifications. If you are 
using the record interface on output, pass only the input file specifications; do not 
pass an output file specification or any of the optional output file arguments. 


org 
OpenVMS usage: byte unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


File organization of the output file, if different from the input file. The org 
argument is the address of a byte whose value specifies the organization of the 
output file; permissible values include the following: 


FABSC_SEQ 
FABSC_REL 
FABSC_IDX 


For the record interface on input, the default value is sequential. For the file 
interface, the default value is the file organization of the first input file for record 
or tag sort and sequential for address and index sort. 


For more information about OpenVMS RMS file organizations, see the OpenVMS 
Record Management Services Reference Manual. 


rfm 

OpenVMS usage: byte _unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


Record format of the output file, if different from the input file The rfm 
argument is the address of a byte whose value specifies the record format of 
the output file; permissible values include the following: 


FABSC_FIX 
FABSC_VAR 
FABSC_VFC 


For the record interface on input, the default value is variable. For the file 
interface, the default value is the record format of the first input file for record or 
tag sort and fixed format for address or index sort. For the mixed interface with 
record interface on input, the default value is variable format. 


For more information about OpenVMS RMS record formats, see the O(pMVMS 
Record Management Services Reference Manual. 


bks 

OpenVMS usage: byte unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


Bucket size of the output file, if different from the first input file. The bks 
argument is the address of a byte containing this size. Use this argument with 
relative and indexed-sequential files only. If the bucket size of the output file is 
to differ from that of the first input file, specify a byte to indicate the bucket size. 
Acceptable values are from 1 to 32. If you do not pass this argument—and the 
output file organization is the same as that of the first input file—the bucket size 
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defaults to the value of the first input file. If the file organizations differ or if the 
record interface is used on input, the default value is 1 block. 


bls 

OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: read only 
mechanism: by reference 


Block size of a magnetic tape output file. The bls argument is the address 

of a word containing this size. Use this argument with magnetic tapes only. 
Permissible values range from 20 to 65,532. However, to ensure compatibility 
with non-HP systems, ANSI standards require that the block size be less than or 
equal to 2048. 


The block size defaults to the block size of the input file magnetic tape. If the 
input file is not on magnetic tape, the output file block size defaults to the size 
used when the magnetic tape was mounted. 


mrs 

OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: read only 
mechanism: by reference 


Maximum record size for the output file. The mrs argument is the address of a 
word specifying this size. Following are acceptable values for each type of file: 


File Organization Acceptable Value 
Sequential 0 to 32,767 
Relative 0 to 16,383 
Indexed sequential 0 to 16,362 


If you omit this argument or if you specify a value of 0, SORT does not check 
maximum record size. 


If you do not specify this argument, the default is based on the output file 
organization and format, unless the organization is relative or the format is fixed. 
The longest output record length is based on the longest calculated input record 
length, the type of sort, and the record format. 


alq 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Number of preallocated output file blocks. The alq argument is the address of a 
longword specifying the number of blocks you want to preallocate to the output 
file. Acceptable values range from 1 to 4,294,967,295. 


Pass this argument if you know your output file allocation will be larger or 
smaller than that of your input files. The default value is the total allocation of 
all the input files. If the allocation cannot be obtained for any of the input files or 
if the record interface is used on input, the file allocation defaults to 1000 blocks. 
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fop 

OpenVMS usage: mask_longword 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


File-handling options. The fop argument is the address of a longword whose bit 
settings determine the options selected. For a list of valid filehandling options, 
see the description of the FAB$L_FOP field in the OpenVMS Record Management 
Services Reference Manual. By default, only the DF W (deferred write) option is 
set. If your output file is indexed, you should set the CIF (create if) option. 


fsz 

OpenVMS usage: byte unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 


Size of the fixed portion of VFC records. The fsz argument is the address of a 
byte containing this size. If you do not pass this argument, the default is the size 
of the fixed portion of the first input file. If you specify the VFC size as 0, RMS 
defaults the value to 2 bytes. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: write only 
mechanism: by reference 


Value that distinguishes between multiple concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


The SOR$PASS FILES routine passes input and output file specifications to 
SORT. The SOR$PASS FILES routine must be repeated for multiple input files. 
The output file name string and characteristics should be specified only in the 
first call to SOR$PASS FILES. 


This routine also accepts optional arguments that specify characteristics for the 
output file. By default, the output file characteristics are the same as the first 
input file; specified output file characteristics are used to change these defaults. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 


SS$ NORMAL 

SOR$ DUP_OUTPUT 
SOR$ ENDDIAGS 
SOR$_INP_FILES 
SOR$_NYI 

SOR$ SORT_ON 
SOR$ SYSERROR 
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Normal successful completion. 

Output file has already been specified. 
Completed with diagnostics. 

Too many input files specified. 

Not yet implemented. 

Sort or merge routine called in incorrect order. 
System service error. 
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SOR$RELEASE_REC—Pass One Record to Sort 


Format 


Returns 


Arguments 


Description 


The SOR$RELEASE_REC routine is used with the record interface to pass one 
input record to SORT or MERGE. 


SOR$RELEASE_REC desc [,context] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


desc 

OpenVMS usage: char_string 

type: character-coded text string 
access: read only 

mechanism: by descriptor 


Input record buffer. The desc argument is the address of a descriptor pointing to 
the buffer containing the record to be sorted. If you use the record interface, this 
argument is required. 


context 

OpenVMS usage: context 
type: longword 
access: modify 
mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Call SOR$RELEASE_REC to pass records to SORT or MERGE with the record 
interface. SOR$RELEASE_REC must be called once for each record to be sorted. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 


SS$ NORMAL 
SOR$ BADLOGIC 
SOR$ BAD_LRL 


SOR$_BAD_SRL 
SOR$ ENDDIAGS 
SOR$ EXTEND 
SOR$ MISS PARAM 
SOR$ NO_WRK 


SOR$ OPENOUT 
SOR$_OPERFAIL 
SOR$ READERR 
SOR$ REQ ALT 


SOR$_RTNERROR 


SOR$ SORT_ON 
SOR$ SYSERROR 
SOR$_USE_ALT 
SOR$ WORK_DEV 
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Normal successful completion. 
Internal logic error detected. 


Record length n greater than longest specified 
record length. 


Record length n too short to contain keys. 
Completed with diagnostics. 

Unable to extend work file for needed space. 
The desc argument is missing. 


Work files required; cannot do sort in memory as 
requested. 


Error opening file as output. 

Error requesting operator service. 

Error reading file 

Specify alternate name file (or nothing to try 
again). 

Unexpected error status from user-written 
routine. 

Sort or merge routines called in incorrect order. 
System service error. 

Using alternate file name 


Work file name must be on random access local 
device. 
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SOR$SRETURN_REC—Return One Sorted Record 


Format 


Returns 


Arguments 


The SOR$RETURN_REC routine is used with the record interface to return one 
sorted or merged record to a program. 


SOR$RETURN_REC desc [,length] [,context] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


desc 

OpenVMS usage: char_string 

type: character-coded text string 
access: write only 

mechanism: by descriptor 


Output record buffer. The desc argument is the address of a descriptor pointing 
to the buffer that receives the sorted or merged record. 


length 

OpenVMS usage: word_unsigned 
type: word (unsigned) 
access: write only 
mechanism: by reference 


Length of the output record. The length argument is the address of a word 
receiving the length of the record returned from SORT/MERGE. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 
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Description 


Call the SOR$¢RETURN_REC routine to release the sorted or merged records toa 
program. Call this routine once for each record to be returned. 


SOR$RETURN_REC places the record into a record buffer that you set up in the 
program's data area. After SORT has successfully returned all the records to the 
program, it returns the status code SS$ ENDOFFILE, which indicates that there 
are no more records to return. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 


Condition Values Returned 


SS$ NORMAL Normal successful completion. 

SOR$ BADLOGIC Internal logic error detected. 

SOR$ ENDDIAGS Completed with diagnostics. 

SOR$ EXTEND Unable to extend work file for needed space. 

SOR$ MISS PARAM A required subroutine argument is missing. 

SOR$ OPERFAIL Error requesting operator service. 

SOR$ READERR Error reading file 

SOR$ REQ ALT Specify alternate name file (or specify nothing to 
simply try again). 

SOR$ RTNERROR Unexpected error status from user-written 
routine. 

SOR$ SORT_ON Sort or merge routines called in incorrect order. 

SOR$ SYSERROR System service error. 

SOR$ USE ALT Using alternate file name 

SOR$_WORK_DEV Work file name must be on random access local 
device. 
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SOR$SORT_MERGE—Sort 


Format 


Returns 


Argument 


Description 


The SOR$SORT_MERGE routine sorts the input records. 


SOR$SORT_MERGE [context] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


After you have passed either the file names or the records to SORT, call the 
SOR$SORT_MERGE routine to sort the records. For file interface on input, 
the input files are opened and the records are released to the sort. For the 
record interface on input, the record must have already been released (by calls 
to SOR$RELEASE REC). For file interface on output, the output records are 
reformatted and directed to the output file. For the record interface on output, 
SOR$RETURN_REC must be called to get the sorted records. 


Some of the return values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, if you want to check for a specific 
status, you should use LIB$MATCH_COND. 
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Condition Values Returned 


SS$ NORMAL 
SOR$ BADDTYPE 
SOR$ BADLENOFF 
SOR$ BADLOGIC 
SOR$ BADOCCURS 
SOR$_ BADOVRLAY 
SOR$ BADPROTCL 
SOR$ BAD_LRL 


SOR$ BAD_TYPE 
SOR$ CDDERROR 
SOR$ CLOSEIN 
SOR$ CLOSEOUT 
SOR$ COL_CHAR 
SOR$ COL_CMPLX 
SOR$ COL_PAD 
SOR$ COL_THREE 
SOR$ ENDDIAGS 
SOR$ EXTEND 
SOR$ ILLBASE 
SOR$ ILLLITERL 


SOR$ ILLSCALE 
SOR$_INCDIGITS 


SOR$_INCNODATA 
SOR$_INCNOKEY 


SOR$_IND_OVR 
SOR$ KEYED 


SOR$ LRL_MISS 
SOR$ MISLENOFF 
SOR$ MULTIDIM 
SOR$ NOTRECORD 
SOR$ NO WRK 


SOR$_OPENIN 
SOR$ OPENOUT 
SOR$ OPERFAIL 
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Normal successful completion. 

Invalid or unsupported CDD data type. 
Length and offset must be multiples of 8 bits. 
Internal logic error detected. 

Invalid OCCURS clause. 

Invalid overlay structure. 

Node is an invalid CDD object. 


Record length n greater than longest specified 
record length. 


Invalid sort process specified. 

CDD error at node name 

Error closing file as input. 

Error closing file as output. 

Invalid character definition. 
Collating sequence is too complex. 
Invalid pad character. 

Cannot define 3-byte collating values. 
Completed with diagnostics. 

Unable to extend work file for needed space. 
Nondecimal base is invalid. 


Record containing symbolic literals is 
unsupported. 


Nonzero scale invalid for floating-point data item. 


Number of digits is inconsistent with the type or 
length of item. 


Include specification references no data keyword, 
at linen. 


Include specification references no keys keyword, 
at linen. 


Indexed output file must already exist. 
Mismatch between SORT/MERGE keys and 
primary file key. 

Longest record length must be specified. 
Length and offset required. 

Invalid multidimensional OCCURS. 

Node name is a name, not a record definition. 


Work files required, cannot do sort in memory as 
requested. 


Error opening file as input. 
Error opening file as output. 
Error requesting operator service. 


SOR$ READERR 
SOR$ REQ ALT 


SOR$ RTNERROR 
SOR$ SIGNCOMPQ 


SOR$ SORT_ON 
SOR$_SPCIVC 
SOR$_SPCIVD 
SOR$_SPCIVF 
SOR$ SPCIVI 
SOR$_SPCIVK 
SOR$_SPCIVP 
SOR$ SPCIVS 
SOR$_SPCIVX 
SOR$ SPCMIS 
SOR$ SPCOVR 
SOR$ SPCSIS 
SOR$_SRTIWA 


SOR$ SYSERROR 
SOR$ UNSUPLEVL 
SOR$_USE_ALT 
SOR$ WORK_DEV 


SOR$ WRITEERR 
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Error reading file 

Specify alternate name file (or nothing to try 
again). 

Unexpected error status from user-written 
routine. 


Absolute Date and Time data type represented in 
1-second units. 


Sort or merge routines called in incorrect order. 
Invalid collating sequence specification, at line n. 
Invalid data type, at line n. 

Invalid field specification, at line n. 

Invalid include or omit specification, at line n. 
Invalid key or data specification, at line n. 
Invalid sort process, at line n. 

Invalid specification, at line n. 

Invalid condition specification, at line n. 
Invalid merge specification, at line n. 
Overridden specification, at line n. 

Invalid sort specification, at line n. 


Insufficient space. Specification file is too 
complex. 


System service error. 
Unsupported core level for record name. 
Using alternate file name 


Work file name must be on random access local 
device. 


Error writing file 
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SOR$SPEC_FILE—Pass a Specification File Name 


Format 


Returns 


Arguments 


The SOR$SPEC _FILE routine is used to pass a specification file or specification 
text to a sort or merge operation. (This routine is not currently supported by the 
high-performance Sort/Merge utility.) 


SOR$SPEC_FILE [spec_file] [,spec_buffer] [,context] 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


spec_file 

OpenVMS usage: char_string 

type: character-coded text string 
access: read-only 

mechanism: by descriptor 


Specification file name. The spec_file argument is the address of a descriptor 
pointing to the name of a file that contains the text of the options requested for 
the sort or merge. The specification file name string and the specification file 
buffer arguments are mutually exclusive. 


spec_buffer 

OpenVMS usage: char_string 

type: character-coded text string 
access: read-only 

mechanism: by descriptor 


Specification text buffer. The spec_buffer argument is the address of a 
descriptor pointing to a buffer containing specification text. This text has the 
same format as the text within the specification file. The specification file name 
string and the specification file buffer arguments are mutually exclusive. 


context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
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initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Call SOR$SPEC FILE to pass a Specification file name or a buffer with 
specification text to a sort or merge operation. Through the use of a specification 
file, you can selectively omit or include particular records from the sort or merge 
operation and specify the reformatting of the output records. (See the Sort Utility 
in the OpenVMS User's Manual for a complete description of specification files.) 


If you call the SOR$SPEC_FILE routine, you must do so before you call any other 
routines. You must pass either the spec_file or spec_buffer argument, but not 
both. 


Some of the return condition values are used with different severities, depending 
on whether SORT/MERGE can recover. Thus, if you want to check for a specific 
status, you should use LIB$MATCH_COND. 


Condition Values Returned 


SOR$ ENDDIAGS Completed with diagnostics. 

SOR$ NYI Not yet implemented. 

SOR$ SORT_ON Sort or merge routine called in incorrect order. 
SOR$ SYSERROR System service error. 
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SOR$STAT—Obtain a Statistic 


The SOR$STAT routine returns one statistic about the sort or merge operation to 
the user program. 


Format 
SOR$STAT code ,result [,context] 
Returns 
OpenVMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 
Arguments 
code 
OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


SORT/MERGE statistic code. The code argument is the address of a longword 
containing the code that identifies the statistic you want returned in the result 
argument. The following table describes the values that are accepted. 


Note The high-performance Sort/Merge utility currently supports only the 
following subset of these values: SOR$K_REC_INP, SOR$K_REC_SOR, SOR$K_ 
REC_OUT, SOR$K_LRL_INP. 


Code 


Description 


SOR$K_IDENT 
SOR$K_REC_INP 
SOR$K_REC_SOR 
SOR$K_REC_OUT 
SOR$K_LRL_INP 
SOR$K_LRL_INT 
SOR$K_LRL_OUT 
SOR$K_NODES 
SOR$K_INI_RUNS 
SOR$K_MRG_ORDER 
SOR$K_MRG_PASSES 
SOR$K_WRK_ALQ 
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Address of ASCII string for version number 
Number of records input 

Records sorted 

Records output 

Longest record length (LRL) for input 
Internal LRL 

LRL for output 

Nodes in sort tree 

Initial dispersion runs 

Maximum merge order 

Number of merge passes 

Work file allocation 
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SOR$STAT 
Code Description 
SOR$K_MBC_INP Multiblock count for input 
SOR$K_MBC_OUT Multiblock count for output 
SOR$K_MBF_INP Multibuffer count for input 
SOR$K_MBF_OUT Multibuffer count for output 


Note that performance statistics (such as direct |/O, buffered I/O, and elapsed 
and CPU times) are not available because user-written routines may affect those 
values. However, they are available if you call LIB$GET] Pl. 


result 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 
access: write only 
mechanism: by reference 


SORT/MERGE statistic value. The result argument is the address of a longword 
into which SORT/MERGE writes the value of the statistic identified by the code 


argument. 

context 

OpenVMS usage: context 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call toa SORT/MERGE routine for 

a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 


The SOR$STAT routine returns one statistic about the sort or merge operation to 
your program. You can call the SOR$STAT routine at any time while the sort or 
merge is active. 


Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 


Condition Values Returned 


SOR$ ENDDIAGS Completed with diagnostics. 

SOR$ MISS PARAM A required subroutine argument is missing. 
SOR$ NYI Functionality is not yet implemented. 
SOR$ SYSERROR System service error. 
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Traceback Facility (TBK) Routines 


The Traceback facility for HP OpenVMS 164 and Alpha systems is a debugging 
tool that provides information (symbolizations) about call stack PCs. In normal 
operation, when a process suffers a fatal unhandled exception, the operating 
system launches Traceback which sends to SYS$OUTPUT the complete call stack 
at the time of the exception. Applications can also directly use the Traceback 
facility to sequentially generate information for an individual call stack PC. 

In this case, the Traceback simply returns information to the caller, not to 
SYS$OUTPUT. This chapter describes this direct Traceback interface. 


21.1 Introduction to TBK Routines 


On 164 systems, the Traceback facility can be invoked at any time by using the 
TBK$Il64 SYMBOLIZE routine. This routine uses a single data structure for its 
inputs and outputs. It can be called from User, Supervisor, or Executive mode. 


Similarly, on Alpha systems, the Traceback facility can be invoked at any 
time using the TBK$ALPHA_SYMBOLIZE routine. This routine uses a single 
data structure for its inputs and outputs and it can be called from USER, 
SUPERVISOR, or EXCECUTIVE mode. 


Section 21.2 provides sample programs showing how to use the TBK routines. 
Section 21.3 is a reference section that provides details about the TBK routines. 


21.2 Using TBK Routines—Example 


This section provides an example program containing three small subroutines to 
illustrate using the TBK $164 SYMBOLIZE routine. The example program runs 
a test to exercise the 164 librt1 call stack walking routines, the TRACE API, 
sysSunwind, and sysSunwind_goto 64. It is presented in three parts with callout 
information that describes the processing: 


¢ Part 1 of the example defines the necessary call stack walking headers, 
TRACE API headers, local subroutines, and a subroutine exception handler 
(see Section 21.2.1). 


e Part 2 issues librt1 call stack walking calls for each of three subroutines, 
defines a pointer toa call stack walk invocation context block, defines storage 
for the return TRACE symbolizations and information, and defines storage 
and initializes the TRACE API parameter block (see Section 21.2.2). 


e Part 3 allocates and initializes the invocation context block and obtains 
the the context handler’s current context. Subroutine subc signals 
into a frame-based handler, subc_handler which walks the stack, calls 
TBK$l64 SYMBOLIZE to symbolize each frame's PC, and then prints out the 
symbolizations (See Section 21.2.3). 
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21.2.1 TBK$I64_SYMBOLIZE Example—Part 1 


The first part of the example defines the necessary call stack walking headers, 
TRACE API headers, local subroutines, and a subroutine exception handler. 


Example 21-1 TBK$I64_SYMBOLIZE Example—Part 1 


$ run/nodebug unwind4 


In subc_handler, ch_cnt = 1 


Call stack: 

image module routine line PC 

UNWIND4 UNWIND4 subc_handler 27271 0000000000030650 
DECCSSHR CSSHELL HANDLER decc$$shell_ handler 5566 FFFFF80208613E50 
DECCSSHR CSSHELL HANDLER decc$$shell handler 0 FFFFFFFF803EC680 
DECCS$SHR CSSHELL HANDLER decc$$shell_ handler 0 FFFFFFFF803E00B0 
UNWIND4 UNWIND4 subc 27409 00000000000310A0 
UNWIND4 UNWIND4 subb 27200 0000000000030300 
UNWIND4 UNWIND4 suba 27187 0000000000030200 
UNWIND4 UNWIND4 main 27175 0000000000030140 
UNWIND4 UNWIND4 __ main 27171 00000000000300E0 
UNWIND4 UNWIND4 __main 0 FFFFFFFF80B72C80 


Continue (versus exit)? [Y/N]: 
/* 
* NOTE: to compile include "/define=(_ NEW STARLET)". 
a 


#include <stdio.h> @ 
#include <stdarg.h> 
#include <starlet.h> 
#include <stddef.h> 
#include <ssdef.h> 
#include <descrip.h> 


/* librtl headers for call stack walking 
“y 


#include <libSroutines.h> @ 
#include <libicb.h> 


/* trace headers for trace api 
#include <tbkdef.h> @ 
#include <tbk$routines.h> 


/* some local subroutines 
*/ 
void suba (void); @ 


void subb (void); 
void subc (void); 


/* a subroutine exception handler 
“f 
int subc_handler (unsigned long int *sigarg, unsigned long int *mecharg) ; 5) 
unsigned long int a cnt, b cnt, c cnt, ch cnt; 
unsigned __inté4 a_invo handle, b invo handle, c_invo_ handle; 
int status; 


(continued on next page) 
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Example 21-1 (Cont.) TBK$I64_SYMBOLIZE Example—Part 1 
int main () 


suba (); 


return 1; 


void suba () 


@ This program runs a test to exercise the 164 librt1 call stack walking 
routines, the TRACE API, sysSunwind, and sys$unwind_ goto 64. 


@® The necessary librt1 call stack walking headers. LIBICB defines the 
invocation context block. LIB$ROUTINES defines the call stack walk 
function prototypes. 


© The necessary TRACE API header files. TBKDEF defines the TRACE_API 
call parameter. TBK$ROUTINES defines the TRACE API function prototype. 


@ This code defines the local subroutines suba, subb, and subc. 


© This code defines a subroutine exception handler. 


21.2.2 TBK$I64_SYMBOLIZE Example—Part 2 


The second part of the example issues librt1 call stack walking calls for each 
of three subroutines, defines a pointer to a call stack walk invocation context 
block, defines storage for the return TRACE symbolizations and information, and 
defines storage and initializes the TRACE API parameter block. 


Example 21-2 TBK$I64_SYMBOLIZE Example—Part 2 


/* Get routine a’s invocation context handle, used in subc_handler 
*/ 


status = lib$ié4 get_curr_invo_handle (&a_invo_handle) ; 1) 


a_cnt++; 
subb (); 


a_cnt++; 
subb (); 


void subb () 


/* Get routine b’s invocation context handle, used in subc_handler 
k 


status = lib$ié4 get_curr_invo_handle (&b invo_ handle) ; 2] 


b cnt++; 
sube (); 


b cnt++; 
sube (); 


(continued on next page) 
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Example 21-2 (Cont.) TBK$I64_SYMBOLIZE Example—Part 2 


b cnt++; 
sube (); 


void sube () 


libSestablish (subc_handler) ; 
/* Get routine c’s invocation context handle, used in subc_handler 
*/ 


status = lib$i64 get_curr_invo handle (&c_invo handle); © 


/* Signal into subc_handler 
libSsignal (c_cnt) ; 
libS$signal (c_cnt) ; 


int subc_handler (unsigned long int *sigarg, unsigned long int *mecharg) 


int status, tbk status=0, callstack depth = 0; 

unsigned int depth; 

/* local pointer for the call stack walk invocation context block 
*] 


INVO_ CONTEXT BLK *myICB; 14) 


/* local storage for image, module, routine names, line number, and image 

* and module base addresses returned by the trace api 

k 

/ 
static char image [128], module [128], routine [128], inquire continue [128]; 
static struct dsc$descriptor_vs image dsc = {125, DSC$K_DTYPE VT, DSCS$K_CLASS VS, &image[0]}; 
static struct dsc$descriptor vs module dsc = {125, DSC$K_DTYPE VT, DSC$K_CLASS VS, &module[0] } 
static struct dsc$descriptor vs routine dsc = {125, DSC$K DTYPE VT, DSC$K CLASS VS, &routine [0 
unsigned int list line; 
unsigned __int6é4 image base addr; 8 
unsigned __int64 module base addr; 


ine 


(continued on next page) 
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Example 21-2 (Cont.) TBK$I64_SYMBOLIZE Example—Part 2 


/* Local storage and setup for the trace api parameter block 


y 


unsigned int 


64 symbolize flags-{0}; © 


TBK_API PARAM params = { 
TBKSK_ LENGTH, /* trace api parameter block length */ 


0 


/* trace api parameter block type, MBZ */ 


TBKSK_ VERSION, /* trace api parameter block length, MBZ */ 


0 


/* reserved, MBZ */ 


0, /* pe, input */ 

0, /* fp, input, not used for 164 */ 

0, /* filename desc, output, not used here */ 

0; /* library module desc, output, not used here */ 

0, /* record number, output, not used here */ 

(struct descriptor *) &image_ dsc, /* image descriptor, output */ 
(struct descriptor *) &module dsc, /* module descriptor, output */ 
(struct descriptor *) &routine dsc, /* routine descriptor, output */ 
&list_line, /* compiler listing line number, output */ 

0, /* relative pc, output, not used here */ 

&image base addr, /* image base address, output */ 

&module_ base addr, /* module base address, output */ 

0, /* malloc routine, input */ 

0, /* free routine, input */ 

&symbolize flags, /* symbolize flags, input */ 


if (*(sigarg+1 
return SS$ 
else 
ch_cnt++; 


printf ("\nIn 
printf ("Call 


status = 1; 


oo 6 8 6 


17) 


/* reserved */ 
/* reserved */ 
; /* reserved */ 


) == SS$ UNWIND) 


_ CONTINUE; 


subc_handler, ch cnt = %d\n", ch cnt); 
stack: \n"); 


A librt1 call stack walk call to get the suba subroutine’s invocation context 
handle used in subc_handler. 


A librt1 call stack walk call to get the subb subroutine's invocation context 
handle used in subc_handler. 


A librt1 call stack walk call to get the subc subroutine's invocation context 
handle used in subc_handler. 


A pointer is defined to a call stack walk invocation context block. 


Storage is defined for the return TRACE symbolizaions and information, 
which includes local storage for image, module, routine names, line number, 
and image and module base addresses returned by the TRACE API. 


Local storage is defined for the TRACE API parameter block, which is 
initialized. 
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21.2.3 TBK$I64_SYMBOLIZE Example—Part 3 


The third part of the example allocates and initializes the invocation context 
block and obtains the the context handler’s current context. Subroutine subc 
signals into a frame-based handler (subc_handler), which walks the stack, 
calls TBK $164 SYMBOLIZE to symbolize each frame's PC, and prints out the 
symbolizations. 


Example 21-3 TBK$I64_SYMBOLIZE Example—Part 3 


/* Walk the call stack top to bottom, symbolize each frame’s PC, and 
* print out the symbolizations. 


* First, create the invocation context block and get my (subc_handler’s) 
* current context. 
*/ 
myICB = (INVO CONTEXT BLK *) lib$ié4 create invo context (); @ 
1ib$ié4 get curr _invo context (myICB) ; 


printf ("image module routine line PCc\n") ; 


while (!(myICB->libicb$v_bottom of stack) s& @ 
((status & 1) != 0)) 


/* Use the PC from the call stack invocation context block. 
* 


params.tbk$q faulting pc = (unsigned _int64) myICB->libicb$ih pc; 3] 
/* Call trace to do the symbolizations. 
“ 


tbk_status = tbk$i64 symbolize (&params); @ 


/* And print out results 
* 


image [*((short *) image) + 2] = 0; 
module [*((short *) module) + 2] = 0; 
routine [*((short *) routine) + 2] = 0; 


(continued on next page) 
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Example 21-3 (Cont.) TBK$I64_SYMBOLIZE Example—Part 3 
/* Print out the tbk$ié4 symbolize info (with formating 


* to align columns). 
ay 
if (*((short *) module) > 8) 


if (*((short *) routine) > 8) 


printf ("%s 


&module 
&routine 
list_line, 

(unsigned __inté4) 


} 


else 


printf ("%s % 
&image [2 
&module [ 
&routine 
list_line, 
(unsigned __inté4) 


else 


if (*((short *) routine) > 8) 


printf ("%s SS 
&image [2 
&module [ 
&routine 
list_line, 
(unsigned __inté4) 


iF 
2 lz 
[2], 


} 


else 

printf ("%s SS 
&image [2 
&module [ 
&routine 
list_line, 
(unsigned __inté4) 


], 
Pale 
[2], 


} 


/* Get the previous call frame. 
x 

status = 

callstack_depth++; 


1ib$i6é4 get prev_invo context (myICB) ; 


%16.16LX\n", 


myICB->libicb$ih pc) ; 


Sl1d $16.16LX\n", 


myICB->libicb$ih pc) ; 


SS old $16.16LX\n", 


myICB->Libicb$ih pc) ; 


oe 
n 
\o 


old $16.16LX\n", 


myICB->libicb$ih pc) ; 


6 


/* Terminate the call stack walk and free up the memory that it used. 


lib$ié4 prev_invo end (myIcB); © 
lib$ié6é4 free invo_ context (myICB) ; 


(continued on next page) 
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Example 21-3 (Cont.) TBK$I64_SYMBOLIZE Example—Part 3 
/* Set up to unwind if we continue execution. 
Pe (ch_cnt) 
/* first, some sysSunwinds @ 


status = sysSunwind (0, 0); 
break; 


status = sysSunwind (&depth, 0); 


depth = 1; 
status = sysSunwind (&depth, 0); 
break; 


depth = 2; 
status = sysSunwind (&depth, 0); 
break; 


/* now, some sys$goto_unwinds 
k 
/ 
case 5: 
status = sys$goto unwind 64 (&c invo handle, 0, 0, 0); 
break; 
case 6: 
status = sys$goto unwind 64 (&b invo handle, 0, 0, 0); 
break; 
case 7: 
status = sys$goto unwind 64 (&a invo handle, 0, 0, 0); 
break; 


default : 
break; 


/* Continue (after unwinding) or exit? Let the user decide. 
* 


printf ("\nContinue (versus exit)? [Y/N]: "); 

gets (inquire continue) ; 

if ((inquire_continue [0] == 'Y’) || (inquire continue [0] == 'y’) 
return SS$ CONTINUE; 


else 
sysSexit (1); 


@ To prepare for walking the call stack, the invocation context block is allocated 
and initialized, and the context handler’s (subc_handler) current context is 
obtained. 


@ Theaall stack is walked from the current context, subc_handler, to the 
bottom of the stack. 


© The essential call stack PC value is provided. On 164 systems, all the 
symbolization is based on a call stack frame’s PC value. 


© A all is made tothe TRACE symbolize routine, TBK $164 SYMBOLIZE, for 
the call frame's PC. This is the call to the TRACE API. The information is 
then printed out. 
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@® The previous call frame context is obtained. 


© Cleanup is performed and and memory used by the call stack walk is 
deallocated. 


@ Unwind is set up to continue program execution. 


21.3 TBK Routines 


This section describes the TBK routines. The TBK$l64 SYMBOLIZE routine is 
for use on 164 systems and the TBK$ALPHA_SYMBOLIZE routine is for use on 
Alpha systems. 
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TBK$I64_SYMBOLIZE—Symbolize a PC on 164 


Format 


Returns 


Argument 


The TBK $164 SYMBOLIZE routine attempts to symbolize a PC, returning as 
much symbolic representation for that location as was requested. 


For information about the TBK symbolize routine for Alpha systems, see the 
information for TBK$ALPHA_SYMBOLIZE later in TBK$ALPHA_SYMBOLIZE. 


TBK$I64_SYMBOLIZE parameter_block 


OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


parmeter_block 
OpenVMS usage: TBK_API_PARAM 


type: structure 
access: modify 
mechanism: by reference 


Table 21-1 shows the values for TBK_API_PARAM (defined in TBKDEF). 


Table 21-1 Values for TBK_API_PARAM 


Field Size Description 

TBK$W_LENGTH Word Input by value, structure length, 
must be TBK$K_LENGTH 

TBK$B_TYPE Byte Input, MBZ 

TBK$B_VERSION Byte Input by value, must be TBK$K _ 
VERSION 

TBK$L_RESERVEDA Longword Reserved for future use, MBZ 

TBK$Q_FAULTING PC Quadword Input by value, call stack frame 
PC 


(continued on next page) 
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Table 21-1 (Cont.) Values for TBK_API_PARAM 


Field 


Size 


Description 


TBK$PQ_ FILENAME DESC 


TBK$PQ 


LIBRARY_MODULE_DESC 


TBK$PQ_ 
RECORD_NUMBER 


TBK$PQ_IMAGE_DESC 


TBK$PQ_MODULE_DESC 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


Optional output by reference (164 
only), pointer (if not requested, 
MBZ) toa fixed-length string 
text descriptor. The descriptor 
must be set up with preallocated 
adequate buffer space. The 
descriptor is filled with the 
image file name. This can be 

a dynamic descriptor (rather 
than fixed-length), but only if the 
caller is in user mode. 


Optional output, pointer (if not 
requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
pre-allocated adequate buffer 
space. The descriptor is filled 

in with library module name if 
the image filename (see previous 
field) is a text library file. This 
can be a dynamic descriptor 
(rather than fixed length) but 
only if the caller is in user mode. 


Optional output, pointer (if not 
requested, MBZ) to a longword to 
be filled with the relevant image 
file record number. 


Optional output, pointer (if not 
requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
preallocated adequate buffer 
space. The descriptor is filled in 
with the image name. This can 
be a dynamic descriptor (rather 
than fixed length), but only if the 
caller is in user mode. 


Optional output, pointer (if not 
requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
preallocated adequate buffer 
space. The descriptor is filled in 
with the module name. 


(continued on next page) 
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Table 21-1 (Cont.) Values for TBK_API_PARAM 


Field Size Description 
TBK$PQ ROUTINE DESC 64-bit Optional output, pointer (if not 
pointer requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
preallocated adequate buffer 
space. The descriptor is filled in 
with the routine name. 
TBK$PQ_ 64-bit Optional output, pointer (if not 
LISTING LINENO pointer requested, MBZ) to longword to 
be filled in with the line number 
(as show in the modules LIS file). 
TBK$PQ _REL_PC 64-bit Optional output, pointer (if not 
pointer requested, MBZ) to quadword to 
be filled in with the relative PC. 
This can be an image or module 
relative PC. 
TBK$PQ_ MALLOC _RTN 64-bit Optional input, pointer (if not 
pointer supplied, MBZ) address to a user- 
supplied malloc routine. Must 
be supplied when called from 
supervisor or executive mode 
(kernel mode is not supported). 
TBK$PQ_FREE_RTN 64-bit Optional input, pointer (if not 
pointer supplied, MBZ) address toa 
user-supplied free routine. Must 
be supplied when called from 
supervisor or executive mode 
(kernel mode not supported). 
TBK$PQ_ 64-bit Optional input and output, 
SYMBOLIZE FLAGS pointer pointer (if not supplied, MBZ) 
to TBK_SYMBOLIZE_ FLAGS 
(quadword, see below). Used to 
control symbolization options and 
to return additional status. 
TBK$Q RESERVEDO Quadword Reserved for future use, MBZ. 
TBK$Q RESERVED1 Quadword Reserved for future use, MBZ. 
TBK$Q RESERVED2 Quadword Reserved for future use, MBZ. 
TBK$V_ 0 Adjusts the PC value used for 
EXCEPTION_IS FAULT symbolization for target frames 
that suffered a fault exception. 
All Reserved, Must be initialized to 
remaining zero. 
bits 
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Description 


The TBK $164 SYMBOLIZE routine attempts to symbolize a PC, that is, given a 
PC, this routine returns as much of the symbolic representation for that location 
that has been requested: image name, file name, module name, routine name, 
listing line number, file record number, and so on. 


The degree of symbolization depends upon the images symbolic information. 

For best results, compile the images source modules with either traceback (the 
default) or debug information (/DEBUG) and link the image with either traceback 
(/TRACE) or debug (/DEBUG) information. If no symbolic information records 
exists within the image for the PC, then only partial symbolization is possible. 


TBK$l64 SYMBOLIZE can be called by programs in user, supervisor, or executive 
mode. Calls from kernel mode are not allowed; calls when IPL is nonzero are not 
allowed. 


Callers in supervisor or executive mode must supply routines that perform the 
equivilent of malloc and free operations that are legal for the given mode. (The 
C Run Time Library malloc and free routines are only supported in user mode.) 
Pointers to these user-written replacement routines are specified in the TBK$PQ _ 
MALLOC _RTN and TBK$PQ FREE_RTN fields. 


Condition Values Returned 


SS$ KERNELINV This API does not support kernel mode calls. 

SS$ BADPARAM Incorrect TBK_API_PARAM length, type, or 
version. 

SS$_INSFMEM Unable to allocate needed memory. 

SS$ NORMAL Successful completion. 

SS$ ACCVIO Unable to read from the TBK_API_PARAM block. 


Other conditions indicate TRACE failures such as failure status from 
sys$crmpsc_ file 64 on an 164 system. 
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TBK$ALPHA_SYMBOLIZE—Symbolize a call stack PC on Alpha 


The TBK$ALPHA_SYMBOLIZE routine attempts to symbolize a call stack PC, 
returning as much symbolic representation for that location as was requested. 


For information about the TBK symbolize routine for 164 systems, see the 
information for TBK$164_SYMBOLIZE earlier in TBK$l164_SYMBOLIZE. 


Format 
TBK$ALPHA_SYMBOLIZE  parameter_block 


Returns 


OpenVMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


Longword condition value. Most utility routines return a condition value. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Argument 


parmeter_block 
OpenVMS usage: TBK_API_PARAM 


type: structure 
access: modify 
mechanism: by reference 


Table 21-2 shows the values for TBK_API_PARAM (defined in TBKDEF). 


Table 21-2 Values for TBK_API_PARAM on Alpha 


Field Size Description 

TBK$W_LENGTH Word Input by value, structure length, 
must be TBK$K_ LENGTH 

TBK$B_TYPE Byte Input, MBZ 

TBK$B_VERSION Byte Input by value, must be TBK $K _ 
VERSION 

TBK$L_RESERVEDA Longword Reserved for future use, MBZ 

TBK$Q_ FAULTING PC Quadword Input by value, call stack frame 
PC 

TBK$Q_ FAULTING FP Quadword Input by value, call stack Frame 
Pointer 
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Table 21-2 (Cont.) Values for TBK_API_PARAM on Alpha 


Field 


Size 


Description 


TBK$PQ_IMAGE_DESC 


TBK$PQ_MODULE_DESC 


TBK$PQ_ROUTINE_DESC 


TBK$PQ_ 
LISTING LINENO 


TBK$PQ_REL_PC 


TBK$PQ_ 
IMAGE_BASE_ADDR 


TBK$PQ_ 
MODULE_BASE_ADDR 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


64-bit 
pointer 


Optional output, pointer (if not 
requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
preallocated adequate buffer 
space. The descriptor is filled in 
with the image name. This can 
be a dynamic descriptor (rather 
than fixed length) but only if the 
caller is in user mode. 


Optional output, pointer (if not 
requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
preallocated adequate buffer 
space. The descriptor is filled in 
with the module name. 


Optional output, pointer (if not 
requested, MBZ) to a fixed- 
length string text descriptor. The 
descriptor must be set up with 
preallocated adequate buffer 
space. The descriptor is filled in 
with the routine name. 


Optional output, pointer (if not 
requested, MBZ) to longword to 
be filled in with the line number 
(as show in the modules LIS file). 


Optional output, pointer (if not 
requested, MBZ) to quadword to 
be filled in with the relative PC. 
This may be an image or module 
relative PC. 


Optional output, pointer (if not 
requested, MBZ) to quadword to 
be filled in with the image base 
address. 


Optional output pointer (if not 
requested, MBZ) to quadword to 
be filled in with the module base 
address. 
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Table 21-2 (Cont.) Values for TBK_API_PARAM on Alpha 


Field Size Description 
TBK$PQ_ MALLOC _RTN 64-bit Optional input, pointer (if not 
pointer supplied, MBZ) address to a user- 


supplied malloc routine. Must 
be supplied when called from 
supervisor or executive mode 
(kernel mode is not supported). 
TBK$PQ FREE _RTN 64-bit Optional input, pointer (if not 
pointer supplied, MBZ) address to a 
user-supplied free routine. Must 
be supplied when called from 
supervisor or executive mode 
(kernel mode not supported). 
TBK$PQ_ 64-bit Optional input and output, 
SYMBOLIZE FLAGS pointer pointer (if not supplied, MBZ) 
to TBK_SYMBOLIZE FLAGS 
(quadword, see below). Used to 
control symbolization options and 
to return additional status. 


TBK$Q RESERVEDO Quadword Reserved for future use, MBZ. 
TBK$Q RESERVED1 Quadword Reserved for future use, MBZ. 
TBK$Q RESERVED2 Quadword Reserved for future use, MBZ. 
TBK$V_ 0 Adjusts the PC value used for 
EXCEPTION_IS FAULT symbolization for target frames 
that suffered a fault exception. 
All Reserved. Must be initialized to 
remaining zero. 
bits 
Description 


The TBK$ALPHA_SYMBOLIZE routine attempts to symbolize a PC. That is, 
given a PC and a frame pointer, this routine returns as much of the symbolic 
representation for that location that has been requested: image name, file name, 
module name, routine name, listing line number, file record number, and so on. 
This must be a PC in an active call stack frame. 


The degree of symbolization depends on the images symbolic information. For 
best results, compile the image source modules with either traceback (the default) 
or debug information (/DEBUG), and link the image with either traceback 
(TRACE) or debug (/DEBUG) information. If no symbolic information records 
exists within the image for the PC, then only partial symbolization is possible 


The TBK$ALPHA_SYMBOLIZE routine can be called by programs in user, 
supervisor, or executive mode. Calls from kernel mode are not allowed; calls 
when IPL is nonzero are not allowed. 


Callers in supervisor or executive mode must supply routines that perform the 
equivalent of malloc and free operations that are legal for the given mode. (The 
C Run Time Library malloc and free routines are only supported in user mode.) 
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Pointers to these user-written replacement routines are specified in the TBK$PQ _ 
MALLOC _RTN and TBK$PQ FREE RTN fields. 


Condition Values Returned 


SS$ KERNELINV 
SS$ BADPARAM 


SS$ INSFMEM 
SS$ NORMAL 
SS$ ACCVIO 


This API does not support kernel mode calls. 


Incorrect TBK_API_PARAM length, type, or 
version. 


Unable to allocate needed memory. 
Successful completion. 
Unable to read from the TBK_API_PARAM block. 
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A 


Absolute time 
defined, DECdts-2 
example of, DECdts-2 
ISO representation of, DECdts-2 
variations on |SO representation of, DECdts-2 
Absolute Time routine, DECdts-13 
Access control list editor routines 
See ACL editor routines 
ACL editor routines 
editing, ACL-3 
example of BLISS program, ACL-1 
manipulating, ACL-1 
options available, ACL-4 
ACLEDIT$EDIT routine, ACL-3 
ACLEDT$SECTION logical name, ACL-5 
ACLs (access control lists) 
See ACL editor routines 
Add Time routine, DECdts-15 
Advanced Encryption Standard (AES) 
features, ENC-2 
Any Time routine, DECdts-17 
Any Zone routine, DECdts-20 
Applications 
linking DECdts shared image with, DECdts-8 
ASCII Any Time routine, DECdts-22 
ASCII GMT Time routine, DECdts-24 
ASCII Local Time routine, DECdts-26 
ASCII Relative Time routine, DECdts-28 
ASCII text strings 
binary timestamps translated to, DECdts-1 


Backup API, BCK-1 

example of C program, BCK-2 
BACKUP$START, BCK-4 
BIH, DECdts-1 
Binary data, compression of, DCX-1 
Binary Relative Time routine, DECdts-29 
Binary Time routine, DECdts-31 
Binary timestamp, DECdts-6 
Bound Time routine, DECdts-33 


Index 


Buckets 
recdaiming with CONV$RECLAIM routine, 
CONV-20 
reclamation statistics, CONV-21 


C 


Callable interface of DECTPU routines, 
DECTPU-1 
Calling Standard 
requirements, ENC-4 
CLI routines, CLI-1 
See also Command strings 
example in a Fortran program, CLI-2 
list of, CLI-1 
when to use, CLI-1 
CLI$DCL_PARSE routine, CLI-5 
CLI$DISPATCH routine, CLI-8 
CLI$GET_VALUE routine, CLI-9 
CLI$PRESENT routine, CLI-12 
Command language definition file 
template for UTIL$CQUAL_FILE_PARSE, 
CQUAL-6 
Command language interface routines 
See CLI routines 
Command line qualifiers, CQUAL-2 
Command strings 
See also CLI routines 
checking for presence of, CLI-12 
dispatching to action routine, CLI-8 
obtaining values, CLI-9 
parsing a DCL command string, CLI-5 
positional qualifiers, CLI-13 
processing with CLI routines, CLI-1 
prompting for input, CLI-6 
Command tables 
using with CLI routines, CLI-1, CLI-6 
Common file qualifier routines, CQUAL-1 
Compare Interval Time routine, DECdts-35 
Compare Midpoint Times routine, DECdts-38 
Context variables, with DCX routines, DCX-17 
CONV$CONVERT routine, CONV-8 
CONV$PASS FILES routine, CONV-12 
CONV$PASS OPTIONS routine, CONV-15 
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CONV$RECLAIM routine, CONV-20 
CONVERT command 

list of qualifiers, CONV-16 

passing options, CONV-15, CONV-18 

setting qualifiers, CONV-15 
CONVERT routines, CONV-1 

examples, CONV-2 to CONV-6 

list of, CONV-1 

using wildcard characters in, CONV-13 
Convert utility (CONVERT) 

conversion statistics, CONV-8 
Convert utility routines 

See CONVERT routines 
Coordinated Universal Time, DECdts-1 


DECats absolute time structures 
listing, DECdts-5 
DECdts API header files, DECdts-7 
<time.h>, DECdts-7 
<utc.h>, DECdts-7 
DECdts API routines 
description, DECdts-1 
sample C program, DECdts-88 
DECdts relative time structures 
listing, DECdts-5 
DECdts routines 
basic functions, DECdts-1 
DECTPU callable interface 
See DECTPU routines 
DECTPU routines, DECTPU-1 


D bound procedure parameter value, DECTPU-3 
callable DECTPU, DECTPU-1 to DECTPU-5 

condition handler, DECTPU-3 to DECTPU-4 

examples, DECTPU-4, DECTPU-7 to 


Data compression 
See also DCX routines 


algorithm for submitting all data records, DECTPU-27 

DCX-16 list of, DECTPU-6 
analysis preceding compression, DCX-14 shareable image, DECTPU-1, DECTPU-3 
size of data after compression, DCX-1 user-written 


FILEIO, DECTPU-68 

FILE_PARSE, DECTPU-70 
FILE_SEARCH, DECTPU-72 
HANDLER, DECTPU-75 
INITIALIZE, DECTPU-76 
requirements, DECTPU-7 

USER, DECTPU-77 

Device access, controlling through access control 
lists, ACL-1 


Data Compression facility routines 
See DCX routines 

Data expansion, DCX-23 
See also DCX routines 
initializing, DCX-26 

Data Expansion facility routines 
See DCX routines 

Data records 
analysis, DCX-13 
compression, DCX-1 E 
conversion, CONV-1 


expansion, DCX-1 EDT routines, EDT-1 
Databases examples, EDT-1, EDT-2 
compressing, DCX-1 user-written 
expanding, DCX-3 FILEIO, EDT-7 
DCL command strings WORKIO, EDT-11 


See Command strings te EPS 
DCX routines, DCX-1 EDT$EDIT routine, EDT-3 


ENCRYPT$DECRYPT routine, ENC-11 
examples, DCX-11 to DCX-29 : : 
DCXSANALYZE DATA routine DCX-12 So ae E_RECORD routine, 
OE eee ae ae ENCRYPT$DEFINE_KEY routine, ENC-17 
Bee POEs ene ENCRYPT$DELETE_KEY routine, ENC-20 

DCX$COMPRESS DATA routine, DCX-18 = 


GEASCOMPRESS DONE rowne exz0 -ENCRYPTSENCRYET rate, ENC-Z2 
DCX$COMPRESS INIT routine, DCX-21 = ’ 


DCX$EXPAND_DATA routine, DCX-23 a eee E RECORD routine, 
DCX$EXPAND_DONE routine, DCX-25 


DCRSEXPAND INIT ratineOCK-2 te cies: 
DCX$MAKE_MAP routine, DCX-28 = , 


. “f . ENCRYPT$INIT routine, ENC-35 
DEC Text Processing Utility roukines ENCRYPT$STATISTICS routine, ENC-38 
See DECTPU routines 
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Encryption 
ENCRYPT routines, ENC-1 
Encryption routines, ENC-1 
AES features, ENC-2 
bitmasks, ENC-10 
DES key and data semantics, ENC-6 
descriptions of routines, ENC-9 
ENCRYPT$DECRYPT, ENC-11 
ENCRYPT$DECRYPT_ONE_ RECORD, 
ENC-14 
ENCRYPT$DEFINE_ KEY, ENC-17 
ENCRYPT$DELETE KEY, ENC-20 
ENCRYPT$ENCRYPT_ FILE, ENC-25 
ENCRYPT$ENCRYPT_ONE_ RECORD, 
ENC-29 
ENCRYPTS$FINI, ENC-32 
ENCRYPT$GENERATE KEY, ENC-33 
ENCRYPTSINIT, ENC-35 
ENCRYPT$STATISTICS, ENC-38 
error handling, ENC-10 
how they work, ENC-4 
maintaining keys, ENC-8 
operations on files, ENC-9 
operations on records and blocks, ENC-9 
specifying arguments, ENC-9 
Encrypton routines 
ENCRYPT$ENCRYPT, ENC-22 


F 


FDL routines, FDL-1 
See also FDL specifications 
examples, FDL-3 to FDL-6 
FDL specifications 
See also FDL routines 
creating, FDL-7 
default attributes, FDL-10, FDL-17 
generating, FDL-13 
in character string, FDL-2, FDL-9 
parsing, FDL-16 
semicolons as delimiters, FDL-2 
with CONVERT routines, CONV-16 
FDL$CREATE routine, FDL-7 
FDL$GENERATE routine, FDL-13 
FDL$PARSE routine, FDL-16 
FDL$RELEASE routine, FDL-19 
File access, controlling through access control lists, 
ACL-1 
File Definition Language routines 
See FDL routines 
File organization, changing with CONVERT 
routines, CONV-1 
File specifications, using with CONVERT routines, 
CONV-13 
Files 
compressing, DCX-1 
expanding, DCX-3 


Files (cont’d) 
Prolog 3 indexed files, CONV-1, CONV-20 
Full callable interface of DECTPU routines, 
DECTPU-2, DECTPU-5 


G 


Get Time routine, DECdts-41 

Get User Time routine, DECdts-42 

Global sections, controlling access through access 
control lists, ACL-1 

Greenwich Mean Time (GMT), DECdts-1 

Greenwich Mean Time routine, DECdts-43 

Greenwich Mean Time Zone routine, DECdts-45 


H 


Headers 

library, LBR-24 

library module, LBR-23 
Help libraries, displaying text, LBR-26 
HP SSL 

using with LDAP, LDAP-43 


Images, compression of, DCX-1 
Inaccuracy, DECdts-2 
International Standards Organization 
8601 standard, DECdts-2 
International Time Bureau, DECdts-1 
ISO format, DECdts-2 
commas as separators in, DECdts-3 
example, DECdts-2 
example of, DECdts-2 
example showing variations, DECdts-3 
specifying inaccuracy, DECdts-2, DECdts-3 
TDF in, DECdts-2 
use of | delineator, DECdts-2 
use of plus (+) or minus (-) characters, 
DECdts-3 
use of the T delineator, DECdts-3 
variations to, DECdts-2 
Item lists 
with ACL editor routine, ACL-3 
with DECTPU routines, DECTPU-62 


J 


J ob controllers 
function, PSM-3 
request to symbiont, SMB-5 


Index—3 


K 


Keys (in records) 
See Sort/Merge utility 
Keyword paths 
obtaining values of command string keywords, 
CLI-9 
referencing command string keywords, CLI-12 


L 


LBR routines, LBR-1 
control index, LBR-7 
data records 
reading, LBR-48 
writing, LBR-73 
end-of-module record, writing, LBR-68 
examples, LBR-7 to LBR-19 
creating a new library, LBR-9 
deleting a module from a library, LBR-17 
to LBR-19 
inserting a module into a library, LBR-11 
to LBR-14 
header, LBR-3 
help text 
outputting, LBR-64 
retrieving, LBR-40 
index, LBR-3 
index search, return key, LBR-56 
index searching, LBR-79 
library 
closing, LBR-29 
creating, LBR-60 
opening, LBR-60 
structure, LBR-3 toLBR-5 
types, LBR-1 
library file, flushing, LBR-36 
library header information, LBR-38 
library index 
getting contents, LBR-45 
initializing, LBR-50 
searching for key, LBR-45 
library key, LBR-3 
creating ASCII or binary, LBR-61 
deleting, LBR-32 
finding, LBR-34 
inserting, LBR-52 
looking up, LBR-54 
replacing, LBR-75 
library update history record, retrieving, 
LBR-43 
locate mode, setting record access mode to, 
LBR-84 
map module (164), LBR-58 
module, LBR-3 
accessing with RFA, LBR-34 
deleting data records, LBR-30 
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LBR routines 
module (cont’d) 
headers, LBR-85 
move mode, setting record access to, LBR-87 
put module into current library (164), LBR-71 
RMS status value, returning, LBR-78 
setting current index number, LBR-82 
summary, LBR-7 
unmap module from process P2 space (| 64), 
LBR-88 
update history records, writing, LBR-69 
virtual memory, recovering, LBR-36 
LBR$CLOSE routine, LBR-8, LBR-29 
LBR$DELETE_DATA routine, LBR-17, LBR-30 
LBR$DELETE_KEY routine, LBR-17, LBR-32 
LBR$FIND routine, LBR-34 
LBR$FLUSH routine, LBR-36 
LBR$GET_HEADER routine, LBR-24, LBR-38 
LBR$GET_HELP routine, LBR-40 
LBR$GET_HISTORY routine, LBR-43 
LBR$GET_INDEX routine, LBR-27, LBR-45 
LBR$GET_RECORD routine, LBR-15, LBR-48 
LBR$INI_CONTROL routine, LBR-8, LBR-50 
LBR$INSERT_KEY routine, LBR-11, LBR-52 
LBR$LOOKUP_KEY routine, LBR-11, LBR-15, 
LBR-17, LBR-23, LBR-54 
LBR$LOOKUP_TYPE routine, LBR-56 
LBR$MAP_MODULE routine, LBR-58 
LBR$OPEN routine, LBR-7, LBR-8, LBR-60 
LBR$OUTPUT_HELP routine, LBR-26, LBR-64 
LBR$PUT_END routine, LBR-11, LBR-68 
LBR$PUT_HISTORY routine, LBR-69 
LBR$PUT_MODULE routine, LBR-71 
LBR$PUT_RECORD routine, LBR-11, LBR-73 
LBR$REPLACE KEY routine, LBR-11, LBR-75 
LBR$RET_RMSSTV routine, LBR-78 
LBR$SEARCH routine, LBR-79 
LBR$SET_INDEX routine, LBR-82 
LBR$SET_LOCATE routine, LBR-84 
LBR$SET MODULE routine, LBR-23, LBR-85 
LBR$SET_MOVE routine, LBR-87 
LBR$UNMAP_MODULE routine, LBR-88 
LDAP, LDAP-1 
HP SSL certificate options, LDAP-43 
sample LDAP API code, LDAP-44 
using with HP SSL for OpenVMS, LDAP-43 
LGI callouts, LGI-3 
LGI$I1CB_ACCTEXPIRED callback routine, 
LGI-35 
LGI$1CB_AUTOLOGIN callback routine, LGI-36 
LGI$I1CB_CHECK_PASS callback routine, LGI-37 
LGI$ICB_DISUSER callback routine, LGI-38 
LGI$I1CB_GET_INPUT callback routine, LGI-39 
LGI$I1CB_GET_SYSPWD aallback routine, 
LGI-40 


LGI$1CB_MODALHOURS callback routine, 
LGI-41 
LGI$ICB_PASSWORD callback routine, LGI-42 
LGI$I1CB_PWDEXPIRED callback routine, 
LGI-44 
LGI$I1CB_USERPARSE callback routine, LGI-45 
LGI$l1CB_USERPROMPT callback routine, 
LGI-46 
LGI$ICB_VALIDATE callback routine, LGI-47 
LGI$1ICR_AUTHENTICATE callout routine, 
LGI-15 
LGI$1ICR_CHKRESTRICT callout routine, 
LGI-18 
LGI$l1CR_DECWINIT callout routine, LGI-20 
LGI$ICR_FINISH callout routine, LGI-22 
LGI$lICR_IACT_START callout routine, LGI-24 
LGI$ICR_IDENTIFY callout routine, LGI-26 
LGI$ICR_INIT routine, LGI-28 
LGI$ICR_J OBSTEP callout routine, LGI-30 
LGI$l|CR_LOGOUT callout routine, LGI-32 
LIB$INSERT_KEY routine, LBR-20 
LIB$SET_INDEX routine, LBR-20 
Librarian utility routines 
See LBR routines 
Libraries 
closing, LBR-8 
deleting module, LBR-17 
initializing, LBR-8 
inserting module, LBR-11 
listing index entries, LBR-27 
module header, LBR-23 
multiple indexes, LBR-20 
multiple keys, LBR-20 
opening, LBR-7, LBR-8 
processing index entry, LBR-27 
replacing module, LBR-11 
Library 
DECdts, DECdts-8 
Lightweight Directory Access Protocol (LDAP), 
LDAP-1 
Local Time routine, DECdts-48 
Local Zone routine, DECdts-50 
LOGINOUT callback routines, LGI-34 to LGI-48 
LOGINOUT callout routines, LGI-14 to LGI-33 


LOGINOUT callouts 
See LGI callouts 
LOGINOUT sample program, LGI-10 


Mail utility (MAIL), MAIL-1 
action routine, MAIL-7 
calling sequence, MAIL-8 
folder, MAIL-11, MAIL-14 
mail file, MAIL-14 
send, MAIL-16 
address list, MAIL-16 


Mail utility (MAIL) 

address list (cont’d) 

creating, MAIL-16 

user name type, MAIL-16 
bodypart, creating, MAIL-15 
condition handling, MAIL-6 
context, MAIL-3 

initiating, MAIL-4 

mail file. MAIL-9 

message, MAIL-11 

send, MAIL-14 

terminating, MAIL-4 

user profile, MAIL-17 
deleted bytes threshold, MAIL-11 
disk space, reclaiming, MAIL-11 
folder, MAIL-2 

creating, MAIL-14 

deleting, MAIL-14 
folder names, displaying, MAIL-11 
item code, MAIL-7 

input, MAIL-7, MAIL-18 

output, MAIL-7, MAIL-21 
item descriptor 

declaring, MAIL-7 

null, MAIL-7 
item list, MAIL-6 

declaring, MAIL-7 

terminating, MAIL-7 
mail file) MAIL-3 

alternate, MAIL-10 

closing, MAIL-9 

compressing, MAIL-11 

creating, MAIL-14 

default, MAIL-9 

opening, MAIL-9 

purging, MAIL-11 

specifying, MAIL-9 to MAIL-10 

wastebasket, MAIL-11 
mail file context 

initiating, MAIL-9 

terminating, MAIL-9 
message attributes, creating, MAIL-15 
message context 

initiating, MAIL-12 

terminating, MAIL-12 
message format, standard, MAIL-1 
message header, creating, MAIL-15 
message ID, external, MAIL-2 
messages, MAIL-1 

attribute, MAIL-15 

copying, MAIL-13 

creating, MAIL-15 

deleting, MAIL-14 

displaying, MAIL-13 

marking, MAIL-13 

modifying, MAIL-13 

moving, MAIL-13 

printing, MAIL-13 
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Mail utility (MAIL) 
messages (cont'd) 
reading, MAIL-13 
selecting, MAIL-12 
sending, MAIL-15, MAIL-16 
null item list, MAIL-7 
programming examples, MAIL-23 
send context, MAIL-14 to MAIL-15 
signaling error, MAIL-6 
thread, MAIL-5 
user profile database, MAIL-3, MAIL-17 
user profile entry, MAIL-3, MAIL-17 
adding, MAIL-18 
deleting, MAIL-18 
flags, MAIL-18 
form, MAIL-18 
forwarding address, MAIL-18 
modifying, MAIL-18 
personal name, MAIL-18 
queue name, MAIL-18 
MAIL$MAILFILE_BEGIN routine, MAIL-32 
MAIL$MAILFILE_CLOSE routine, MAIL-34 
MAIL$MAILFILE_COMPRESS routine, MAIL-36 
MAIL$MAILFILE_END routine, MAIL-39 
MAIL$MAILFILE_INFO_FILE routine, MAIL-41 
MAIL$MAILFILE_MODIFY routine, MAIL-44 
MAIL$MAILFILE_OPEN routine, MAIL-47 
MAIL$MAILFILE_PURGE_WASTE routine, 
MAIL-50 
MAIL$MESSAGE BEGIN routine, MAIL-53 
MAIL$MESSAGE_COPY routine, MAIL-55 
MAIL$MESSAGE_DELETE routine, MAIL-59 
MAIL$MESSAGE_END routine, MAIL-61 
MAIL$MESSAGE_GET routine, MAIL-63 
MAIL$MESSAGE_INFO routine, MAIL-68 
MAIL$MESSAGE_ MODIFY routine, MAIL-72 
MAIL$MESSAGE_ SELECT routine, MAIL-75 
MAIL$SEND_ABORT routine, MAIL-78 
MAIL$SEND_ADD_ADDRESS routine, MAIL-80 
MAIL$SEND_ADD_ATTRIBUTE routine, 
MAIL-82 
MAIL$SEND_ADD_BODYPART routine, 
MAIL-85 
MAIL$SEND_BEGIN routine, MAIL-88 
MAIL$SEND_END routine, MAIL-91 
MAIL$SEND_MESSAGE routine, MAIL-93 
MAIL$USER_BEGIN routine, MAIL-95 
MAIL$USER_DELETE_INFO routine, MAIL-98 
MAIL$USER_END routine, MAIL-100 
MAIL$USER_GET_INFO routine, MAIL-102 
MAIL$USER_SET_INFO routine, MAIL-106 
Mailboxes, controlling access through access 
control lists, ACL-1 
Make Any Time routine, DECdts-52 
Make ASCII Relative Time routine, DECdts-55 
Make ASCII Time routine, DECdts-57 
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Make Binary Relative Time routine, DECdts-59 

Make Binary Time routine, DECdts-60 

Make Greenwich Mean Time routine, DECdts-62 

Make Local Time routine, DECdts-64 

Make Relative Time routine, DECdts-66 

Make VMS Any Time routine, DECdts-68 

Make VMS Greenwich Mean Time routine, 
DECdts-70 

Make VMS Local Time routine, DECdts-71 

Multiply a Relative Time by a Real Factor routine, 
DECdts- 73 

Multiply Relative Time by an Integer Factor 
routine, DECdts-75 


N 


National character set (NCS) routines 

See NCS routines 
NCS routines 

C program sample, NCS-2 

Fortran program sample, NCS-2 

list of, NCS-1 

typical application of, NCS-2 
NCS$COMPARE routine, NCS-7 
NCS$CONVERT routine, NCS-9 
NCS$END_CF routine, NCS-11 
NCS$END_CS routine, NCS-12 
NCS$GET_CF routine, NCS-13 
NCS$GET_CS routine, NCS-15 
NCS$RESTORE_CF routine, NCS-17 
NCS$RESTORE_CS routine, NCS-19 
NCS$SAVE_CF routine, NCS-21 
NCS$SAVE_CS routine, NCS-23 


O 


Object Library 
DECdts, DECdts-8 
OpenVMS Calling Standard 
requirements, ENC-4 
OpenVMS Greenwich Mean Time routine, 
DECdts-85 
OpenVMS Local Time routine, DECdts-87 
OpenVMS RMS 
See RMS 
OpenVMS time structure, DECdts-7 
Options, creating with LBR$OPEN routine, 
LBR-8 


P 


Point Time routine, DECdts-76 

Print Symbiont Modification routines 
See PSM routines 

Print symbionts 


See Symbionts 


Programs 
linking DECdts shared image with, DECdts-8 
Prolog 3 indexed files 
creating with CONVERT routines, CONV-17 
reclaiming, CONV-20 
with Convert/Reclaim utility, CONV-1 
Prolog files, using with CONVERT routines, 
CONV-17 
Prompt strings, setting with CLI$DCL_PARSE, 
CLI-7 
PSM routines, PSM-1 
examples, PSM-16 to PSM-20 
USER-FORMAT-ROUTINE, PSM-33 
USER-INPUT-ROUTINE, PSM-37 
USER-OUTPUT-ROUTINE, PSM-43 
PSM$PRINT routine, PSM-21 
PSM$READ_ITEM_DxX routine, PSM-23 
PSM$REPLACE routine, PSM-25 
PSM$REPORT routine, PSM-30 


Q 


Queues 
execution of, PSM-3 
generic, PSM-3 


R 


Records 
See Data records 
Relative time 
calendar date field, DECdts-4 
defined, DECdts-3 
example of, DECdts-4 
negative, DECdts-4 
positive, DECdts-4 
Relative Time routine, DECdts-78 
reltimespec structure declaration, DECdts-7 
reltimespec time structure, DECdts-7 
RMS 
control blocks with FDL routines, FDL-16, 
FDL-19 
Routines 
syntax descriptions, ENC-10 to FDL-1 


S 


Sample C program, DECdts-88 
compiling and linking 
ULTRIX systems, DECdts-90 
VMS systems, DECdts-90 
using routines 
utc_ascgmtime, DECdts-88 
utc_asclocaltime, DECdts-88 
utc_cmpintervaltime, DECdts-88 
utc_cmpmidtime, DECdts-88 
utc_mkanytime, DECdts-88 
utc_mkasctime, DECdts-88 


Shared image 

DECdts, DECdts-8 
Simplified callable interface 

See DECTPU routines 
SMB routines, SMB-1 
SMB$CHECK_FOR_MESSAGE routine, SMB-14 
SMB$INITIALIZE routine, SMB-15 
SMB$READ_MESSAGE routine, SMB-17 
SMB$READ_MESSAGE ITEM routine, SMB-20 
SMB$SEND_TO_J OBCTL routine, SMB-30 
SOR routines, SOR-4 

examples, SOR-8 to SOR-27 

interface 

file. SOR-5 
record, SOR-5 

list of, SOR-4 

reentrancy using context argument, SOR-6 
SORS$$STAT routine, SOR-60 
SOR$BEGIN_MERGE routine, SOR-28 
SOR$BEGIN_SORT routine, SOR-35 
SOR$DTYPE routine, SOR-41 
SOR$END_SORT routine, SOR-44 
SOR$PASS FILES routine, SOR-46 
SOR$RELEASE REC routine, SOR-51 
SOR$RETURN_REC routine, SOR-53 
SOR$SORT_MERGE routine, SOR-55 
SOR$SPEC _FILE routine, SOR-58 
Sort/Merge routines 

See SOR routines 
Sort/Merge utility (high-performance), SOR-1 
Sort/Merge utility (GORT/MERGE) 

See also SOR routines 

See also Sort/Merge utility (high-performance) 

keys, SOR-4 
Span Time routine, DECdts-80 
Subtract Time routine, DECdts-82 
Symbiont thread, PSM-3 
Symbiont/) ob Controller Interface routines 


See SMB routines 
Symbionts 
See also Queues 
active stream, PSM-3 
allocating memory, SMB-4 
carriage control, processing of, PSM-10 
connecting to a device, SMB-4 
demand input routines, PSM-5 
device, PSM-2 
environments, SMB-5 
function of, PSM-3, SMB-2 
input, PSM-2, SMB-1 
INPSMB.EXE file, SMB-1 
internal logic, PSM-4 
main format routine, PSM-12 
main input routine, PSM-9 
main output routine, PSM-13 
invoking, PSM-21 
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Symbionts (cont'd) tm time structure, DECdts-6 


job controller requests, SMB-5 TPU$CLEANUP routine, DECTPU-28 
asynchronous, SMB-6 TPU$CLIPARSE routine, DECTPU-32 
processing, SMB-10 TPU$CLOSE_TERMINAL routine, DECTPU-34 
reading, SMB-10 TPU$CONTROL routine, DECTPU-35 
responding, SMB-13 regaining control from, DECTPU-35, 
synchronous, SMB-5 DECTPU-53 
job controller, communication with, SMB-1 TPU$EDIT routine, DECTPU-37 
modifying, PSM-1, PSM-6, SMB-3 TPU$EXECUTE_COMMAND routine, 
format routine, PSM-11 DECTPU-39 
guidelines, PSM-7 TPU$EXECUTE_INIFILE routine, DECTPU-40 
initialization routine, PSM-14 TPU$FILEIO routine, DECTPU-42 
input routine, PSM-9 TPUSHANDLER routine, DECTPU-52 
integration of routines, PSM-15 TPU$MESSAGE routine, DECTPU-61 
output routine, PSM-12 TPU$PARSEINFO routine, DECTPU-62 
restrictions, PSM-7 TPU$SPECIFY_ASYNC_ACTION routine, 
multiple streams, PSM-3, SMB-9 DECTPU-6, DECTPU-35, DECTPU-53, 
multithreaded, PSM-3 DECTPU-64 
output, PSM-2, SMB-1 TPU$TPU routine, DECTPU-66 
PRTSMB.EXE file, SMB-1 TPU$TRIGGER_ASYNC_ ACTION routine, 
printer, SMB-1 DECTPU-6, DECTPU-35, DECTPU-53, 
process-permanent file, SMB-4 DECTPU-67 
processing, PSM-1 Traceback facility, TBK-1 
server, PSM-2, SMB-1 TBK routines, TBK-1 
single stream, PSM-3, SMB-9 
system MAXBUF parameter, PSM-6 U 
type, SMB-1 
user-written, PSM-1, SMB-1, SMB-3 USER-FORMAT-ROUTINE, PSM-33 
user-written guidelines, SMB-3 User-written DECTPU routines 
user-written interfaces, PSM-6 See DECTPU routines 
SYS$OUTPUT_HELP routine, LBR-8 UTC, DECdts-1 
utc time structure, DECdts-6 
T <utc.h> header file, DECdts-7 


utc_abstime, DECdts-13 
utc_addtime, DECdts-15 
utc_anytime, DECdts-17 
utc_anyzone, DECdts-20 
utc_ascanytime, DECdts-22 
utc_ascgmtime, DECdts-24 
utc_asclocaltime, DECdts-26 
utc_ascreltime, DECdts-28 


TBK routines, TBK-1 

Alpha, TBK-14 

on 164 systems, TBK-10 
TBK$ALPHA_SYMBOLIZE routine, TBK-14 
TBK$l64 SYMBOLIZE routine, TBK-10 
TDF, DECdts-2 
Text compression, DCX-1 


Text-processing routines utc_binreltime, DECdts-29 
See DECTPU routines utc_bintime, DECdts-31 
Time Differential Factor, DECdts-2 utc_boundtime, DECdts-33 
Time representation utc_cmpintervaltime, DECdts-35 
by DECdts, DECdts-1 utc_cmpmidtime, DECdts-38 
Time structures, DECdts-5 utc_gettime, DECdts-41 
OpenVMS, DECdts-7 utc_getusertime, DECdts-42 
reltimespec, DECdts-7 utc_gmtime, DECdts-43 
timespec, DECdts-7 utc_gmtzone, DECdts-45 
tm, DECdts-6 utc_localtime, DECdts-48 
utc, DECdts-6 utc_localzone, DECdts-50 
<time.h> header file, DECdts-6, DECdts-7 utc_mkanytime, DECdts-52 
timespec structure declaration, DECdts-7 utc_mkascreltime, DECdts-55 
timespec time structure, DECdts-7 utc_mkasctime, DECdts-57 


tm structure declaration, DECdts-6 


Index-8 


utc_mkbinreltime, DECdts-59 
utc_mkbintime, DECdts-60 
utc_mkgmtime, DECdts-62 
utc_mklocaltime, DECdts-64 
utc_mkreltime, DECdts-66 
utc_mkvmsanytime, DECdts-68 
utc_mkvmsgmtime, DECdts-70 
utc_mkvmslocaltime, DECdts-71 
utc_mulftime, DECdts-73 
utc_multime, DECdts-75 
utc_pointtime, DECdts-76 
utc_reltime, DECdts-78 
utc_spantime, DECdts-80 
utc_subtime, DECdts-82 
utc_vmsanytime, DECdts-84 
utc_vmsgmtime, DECdts-85 
utc_vmslocaltime, DECdts-87 


UTIL$¢CQUAL 
example, CQUAL-7 
UTIL$CQUAL routines, CQUAL-1 
UTIL$CQUAL_CONFIRM_ACT, CQUAL-5, 
CQUAL-18 
UTIL$CQUAL_FILE_END, CQUAL-5, 
CQUAL-17 
UTIL$CQUAL_FILE_MATCH, CQUAL-3, 
CQUAL-13 
UTIL$CQUAL_FILE_PARSE, CQUAL-11 
Utility routines 
See also SMB routines, SMB-1 


V 


VMS Any Time routine, DECdts-84 


W 


Wildcard characters, using with CONVERT 
routines, CONV-13 
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